IFВики - Вклад [ru]

SMSQuest

2017-03-22T10:36:15Z

Евг:

Самый популярный редактор для [[URQ]]-игр, написанный [[Евг|Евгом]]. Поддерживает быструю вставку основных функций (загружаемых из редактируемого шаблона), динамически генерируемый список [[локация|локаций]] и предметов [[инвентарь|инвентаря]], предварительное выполнение кода в [[интерпретатор|интерпретаторе]] и др.
Написан на VB. Известный баг - при сохранении на флешку иногда сохраняет пустой файл.

== Ссылки ==
* [http://smsquest.plut.info/smsquest.shtm Официальный сайт SMSQuest] (историческая реконструкция сайта [http://smsquest.plut.info/ smsquest.by.ru])
[[Категория:Глоссарий]] [[Категория:Инструменты]]

FireURQ:Особенности реализации URQL

2014-01-18T09:54:59Z

Евг: /* Предопределенные функции */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

=== Кнопки ===
'''FireURQ''' позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам.
Начиная с версии 1.9.1, формат кнопок таков:
'''btn''' <локация>[(param1, param2, ...)][, <надпись на кнопке>]
Где '''<локация>''' - имя метки, на которую будет совершен переход, '''param1''', '''param1''' и т.д. - параметры, передаваемые в эту локацию, '''<надпись на кнопке>''' - надпись на кнопке, которая отображается на экране. В случае если '''<надпись на кнопке>''' не указана, в качестве надписи используется название метки, куда ведет кнопка.

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

Функция '''_trim''' обрезает пробелы с начала и в конце строки, вызывается как proc _trim(str), где str — строка (строковая переменная или строка в кавычках).

Функция '''_scopy''' копирует кусочек строки, вызывается как proc _scopy(str, start[, len]), где str — строка, start — номер символа в строке, с которого начинать копировать и len — количество копируемых символов. Если параметр len опущен, то строка копируется до конца.

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:54:42Z

Евг: /* Предопределенные функции */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

=== Кнопки ===
'''FireURQ''' позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам.
Начиная с версии 1.9.1, формат кнопок таков:
'''btn''' <локация>[(param1, param2, ...)][, <надпись на кнопке>]
Где '''<локация>''' - имя метки, на которую будет совершен переход, '''param1''', '''param1''' и т.д. - параметры, передаваемые в эту локацию, '''<надпись на кнопке>''' - надпись на кнопке, которая отображается на экране. В случае если '''<надпись на кнопке>''' не указана, в качестве надписи используется название метки, куда ведет кнопка.

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

Функция '''_trim'''' обрезает пробелы с начала и в конце строки, вызывается как proc _trim(str), где str — строка (строковая переменная или строка в кавычках).

Функция '''_scopy''' копирует кусочек строки, вызывается как proc _scopy(str, start[, len]), где str — строка, start — номер символа в строке, с которого начинать копировать и len — количество копируемых символов. Если параметр len опущен, то строка копируется до конца.

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:52:09Z

Евг: /* Кнопки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

=== Кнопки ===
'''FireURQ''' позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам.
Начиная с версии 1.9.1, формат кнопок таков:
'''btn''' <локация>[(param1, param2, ...)][, <надпись на кнопке>]
Где '''<локация>''' - имя метки, на которую будет совершен переход, '''param1''', '''param1''' и т.д. - параметры, передаваемые в эту локацию, '''<надпись на кнопке>''' - надпись на кнопке, которая отображается на экране. В случае если '''<надпись на кнопке>''' не указана, в качестве надписи используется название метки, куда ведет кнопка.

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:51:51Z

Евг: /* Кнопки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

=== Кнопки ===
'''FireURQ''' позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам.
Начиная с версии 1.9.1, формат кнопок таков:
'''btn''' <локация>[(param1, param2, ...)][, <надпись на кнопке>]
Где '''<локация>''' - имя метки, на которую будет совершен переход, '''param1''', '''param1''' и т.д. - параметры, передаваемые в эту локацию, '''<надпись на кнопке>''' - надпись на кнопке, которая отображается на экране. В случае если '''<надпись на кнопке>''' не указана в качестве надписи используется название метки, куда ведет кнопка.

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:51:27Z

Евг: /* Кнопки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

=== Кнопки ===
'''FireURQ''' позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам.
Начиная с версии 1.9.1, формат кнопок таков:
'''btn''' <локация>[(param1, param2, ...)][, <надпись на кнопке>]
Где '''<локация>''' - имя метки, на которую будет совершен переход, '''param1''', '''param1''' и т.д. - параметры, передаваемые в эту локацию), '''<надпись на кнопке>''' - надпись на кнопке, которая отображается на экране. В случае если '''<надпись на кнопке>''' не указана в качестве надписи используется название метки, куда ведет кнопка.

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:51:07Z

Евг: /* Кнопки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

=== Кнопки ===
'''FireURQ''' позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам.
Начиная с версии 1.9.1, формат кнопок таков:
''btn'' <локация>[(param1, param2, ...)][, <надпись на кнопке>]
Где '''<локация>''' - имя метки, на которую будет совершен переход, '''param1''', '''param1''' и т.д. - параметры, передаваемые в эту локацию), '''<надпись на кнопке>''' - надпись на кнопке, которая отображается на экране. В случае если '''<надпись на кнопке>''' не указана в качестве надписи используется название метки, куда ведет кнопка.

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:50:43Z

Евг: /* Текст */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

== Кнопки ==
'''FireURQ''' позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам.
Начиная с версии 1.9.1, формат кнопок таков:
''btn'' <локация>[(param1, param2, ...)][, <надпись на кнопке>]
Где '''<локация>''' - имя метки, на которую будет совершен переход, '''param1''', '''param1''' и т.д. - параметры, передаваемые в эту локацию), '''<надпись на кнопке>''' - надпись на кнопке, которая отображается на экране. В случае если '''<надпись на кнопке>''' не указана в качестве надписи используется название метки, куда ведет кнопка.

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:41:01Z

Евг: /* Создание декораторов */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Чтобы декоратор данного типа был активен, в переменной ''decor_<имя>_enabled'' должна стоять 1.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2014-01-18T09:38:54Z

Евг: /* Переменные декораторов */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
<nowiki>[[текст ссылки|название локации]]</nowiki>

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая <nowiki>[[тропинка|trop]]</nowiki>...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
<nowiki>[[текст ссылки]]</nowiki>
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся <nowiki>[[тропинка]]</nowiki>...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст", "целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

'''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина, высота,] "целевая локация"'''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_enabled''' – если установлен в 0, то декоратор типа TEXTBUTTON неактивен.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:23:20Z

Евг: /* Другое */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.
* Переменная '''fp_filename''' содержит имя файла, с которым работают команды '''fp''', '''fpln''' и '''newfile'''.
[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:21:10Z

Евг: /* Вывод в текстовый файл */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы, в которые ведется запись, должны иметь расширение *.txt. Файлы создаются в той же папке, что и файл игры. В переменной '''fp_filename''' учитывается только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:20:25Z

Евг: /* Вывод в текстовый файл */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''.
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы в которые ведется запись должны иметь расширение *.txt. Все файлы создаются в той же папке, что и файл игры, в переменной '''fp_filename''' содержится только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:19:58Z

Евг: /* Вывод в текстовый файл */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>'''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной '''fp_filename'''
'''fprintln <текст>''' или '''fpln <текст>'''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной '''fp_filename'''.

Все файлы в которые ведется запись должны иметь расширение *.txt. Все файлы создаются в той же папке, что и файл игры, в переменной '''fp_filename''' содержится только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:19:31Z

Евг: /* Вывод в текстовый файл */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln'''' (аналог '''p''' и '''pln''', но только для записи текста в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>''''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной ''''fp_filename'''
'''fprintln <текст>''' или '''fpln <текст>''''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной ''''fp_filename'''.

Все файлы в которые ведется запись должны иметь расширение *.txt. Все файлы создаются в той же папке, что и файл игры, в переменной '''fp_filename''' содержится только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:18:57Z

Евг: /* Текст */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

===Вывод в текстовый файл===

С версии 1.9 '''FURQ''' поддерживает вывод текста в текстовый файл. Делается это при помощи команд '''fp''' и '''fpln'''' (аналог '''p''' и '''pln''' только для записи в файл).

Синтаксис:
'''fprint <текст>''' или '''fp <текст>''''
Оператор дописывает '''текст''' в файл, имя которого содержится в переменной ''''fp_filename'''
'''fprintln <текст>''' или '''fpln <текст>''''
Оператор сохраняет '''текст''' и перевод строки в файл, имя которого содержится в переменной ''''fp_filename'''.

Все файлы в которые ведется запись должны иметь расширение *.txt. Все файлы создаются в той же папке, что и файл игры, в переменной '''fp_filename''' содержится только имя файла, любой путь автоматически игнорируется.

Для работы с переменной '''fp_filename''' существует команда '''newfile''':
'''newfile <имя файла>'''
Команда присваивает переменной '''fp_filename''' имя файла и стирает этот файл. Если же просто присвоить переменную '''fp_filename''', то новые записи будут добавляться к уже существующему файлу.

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:07:44Z

Евг: /* Создание декораторов */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

''Целевая локация''' — имя локации для перехода в кавычках. '''Текст''' — надпись на кнопке. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.
''''Рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

'''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:05:40Z

Евг: /* Создание декораторов */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

'''Текст''' — надпись на кнопке, '''рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки. Надпись на текстовой кнопке можно менять при помощи переменной '''decor_<имя>_text'''.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMGBUTTON''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-23T16:03:20Z

Евг: /* Декораторы */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''TEXTBUTTON''' - декоратор «текстовая кнопка»:

'''decoradd <имя> (x, y[, z]) TEXTBUTTON ["рамка", ] "текст",
"целевая локация"'''

'''Текст''' — надпись на кнопке, '''рамка''' — это название рамки, которая должна быть определена в скине. Рамка применяется если нужно сделать много разных кнопок с разным оформлением. Рамки текстовых кнопок определяются в скине в разделе ресурсов. Если рамку не указать, то кнопка будет по умолчанию с тем же оформлением, что и btn-кнопки.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''CLICKAREA''' – это невидимый прямоугольник, который реагирует на нажатия мыши (клики):

'''decoradd <имя> (x, y[, z]) CLICKAREA ширина, высота, "целевая локация"'''

''Целевая локация''' — имя локации в кавычках. Декоратор поддерживает модификаторы (см. раздел о ссылках), т.е. можно сделать выпадающее меню, переход или локальное действие.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Тип '''IMAGE''' - декоратор «кнопка-картинка»:

''''decoradd <имя> (x, y[, z]) IMGBUTTON "файл-текстура", [tx, ty, ширина,
высота,] "целевая локация"''''

'''файл-текстура''' — это полноцветный PNG с прозрачностью,
'''tx''', '''ty''' — это координаты верхнего левого угла В ПРОСТРАНСТВЕ ТЕКСТУРЫ,
'''ширина''' и '''высота''' — это ширина и высота одного КАДРА.

Кадры должны идти друг за другом в такой последовательности — нормальная, неактивная (disabled), в фокусе, нажатая.

Если '''tx''', '''ty''', '''ширина''' и '''высота''' не указаны, то вся текстура просто делится на четыре кадра по горизонтали. Это удобно, но слишком много текстур вредят скорости работы FURQ. Поэтому, если у вас много кнопок, лучше всё-таки разместить их на одну текстуру.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-08-21T10:29:05Z

Евг: /* Подстановки (#...$ и #%...$) */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://www.ifwiki.ru/FireURQ:%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F#.D0.92.D1.8B.D0.B2.D0.BE.D0.B4_.D0.BF.D0.B5.D1.80.D0.B5.D0.BC.D0.B5.D0.BD.D0.BD.D1.8B.D1.85 руководство].

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

Бычков, Евгений

2013-08-20T09:55:09Z

Евг:

Также известен как [[Евг]], [[brevno]].
Один из самых известных деятелей [[URQ]], разработчик [[SMSQuest]]. Бессменный член жюри на [[ЛОК]].

== Общие факты ==

Уроженец далекой и солнечной Латвии, Евг привнес в URQ-сообщество не только [[SMSQuest|смску]] и [[Белый_бычок|игру про белого бычка]], но и нездоровую долю здорового юмора.
Знаменит изощренной фантазией, выражающейся в темах для [[ЛОК]].
Самый популярный соавтор игр на URQ, особенно незаконченных. Из законченных и удавшихся разработок следует отметить серию [[Лифт|"Лифт"]], написанную совместно с [[Ларри Бэггинс]]ом; из закончившихся, но не удавшихся (по мнению второго автора) - легендарный [[ЗИФ]].
Завсегдатай канала, король латвийского уркинга.
Причастность к скандальным инцидентам с участием адских человекоподобных роботов отрицает.
Также крайне знаменит скандальным римейком песни "Хава Нагила", спетый дуэтом со знаменитым участником URQ-сообщества, скрывающегося под псевдонимом [[ZombX]].

== Любимые фразы (2004 года) ==

* ж)
* О Джозеф
* Мой масса
* Вик, приват
* Вик, форум
* Вик, аплоад
* Вик, мыло
* Хрен ли нам, красивым теткам

==Игры==

* [[Белый бычок]] (2002, [[URQ]])
* [[Умоисступление]] (2009, [[Tweebox]]) -- победитель [[дуэль|дуэли]]
* [[Последнее тело]] (2009, [[URQ]]) -- второе место на [[ЛОК 2009]], победитель [[дуэль|дуэли]]
* [[Человек из никогда]] (2011, [[URQ]]/[[Instead]]) -- участник [[дуэль|дуэли]], лучший сюжет года по мнению публики ([[Золотой Хомяк 2011]])

===В соавторстве===
* [[2Viс]] ([[Goraph]], [[Korwin]], [[Terracon]], [[Евг]], 2004, [[URQ]])
* [[ЗИФ]] ([[Евг]] и [[Goraph]], 2005, [[URQ]]) -- второе место на [[Новогодний Блиц-конкурс 2004-2005|Новогоднем Блице]]
* [[Хроники капитана Блуда: Тайна гипсовых фаллоимитаторов]] ([[Goraph]] & [[Евг]], 2008,[[Tweebox]])
* [[Во ржи: куча неприятностей]] ([[Евг]], [[Xlomid]] и [[MS Alzheimer]], 2009, [[URQ]]) -- лучший персонаж года ([[Золотой Хомяк 2009]])
* [[SHOOT YOUR EVIL TWIN BROTHER WHO HAS TRAPPED YOU IN A MIRROR ROOM AND WHO DRINKS PEOPLE'S BLOOD]] ([[Евг]] и [[Xlomid]], [[URQ]]) -- 4е место на [[TWIFcomp]] 2010
* [[С новым годом, Алиса!]] ([[Аджента]], [[Вета]], [[Гораф]], [[Евг]], [[Чикаго]], идея [[Туголуков, Евгений|Корвина]], 2011, [[URQ]]) -- участник конкурса [[Буквица]]

== Конкурсы ==
* [[ЛОК]] (создание/проведение, 2004 - ..)
* [[Вжж!]] (создание/проведение, 2010 - ..)
* [[КРИЛ]] (проведение, 2010 - 2012)

==Ссылки==
* [[ifwiki-en:Evgeny Bychkov|Страничка Евга на ifwiki.org]]
* [http://www.urq.eclub.lv/EvgFAQ.html FAQ]
* [http://plut.info Сайт]
* [http://kril.ifiction.ru Блог КРИЛ]

[[Категория:Персоналии]]

Павленко, Юрий

2013-08-20T09:53:47Z

Евг:

'''Юрий Павленко''' (он же '''Goraph''', он же '''Гораф''', он же '''Гор''')

== Общие факты ==
* Известный персонаж в мире русской [[ИЛ]], особенно в [[URQ]] сообществе.
* На рубеже 2005 и 2006 годов проводил и обозревал [[Зимний Конкурс 2005-2006|Зимний конкурс]].
* Автор множества замечательных игр на [[URQ|урке]], [[RTADS|Тадсе]] и других платформах (постоянно пробует новые). Среди наиболее известных его работ - незавершенная серия игр про [[Капитан Блуд|Капитана Блуда]] ([[Хроники капитана Блуда: Тайна левой ягодицы]] на [[URQ]], [[Хроники капитана Блуда: Тайна китайского чая со льдом]] на [[RTADS]]), серия игр про видру ([[Как видра, йожык и коъот бъолки памахали]] и др.).
* Будущий лучший начинающий писатель Украины. Уже имеет на своем счету опубликованный(ные) рассказ(ы) в сборнике начинающих авторов.
* Прекрасный импровизатор. Может за несколько минут во всех подробностях придумать увлекательный сюжет для игры, чтобы потом несколько лет откладывать её написание. А когда, наконец, начинает писать эту игру, понять, что уже забыл всё, что когда-то придумал.
* Имеет в запасе и в разработке не менее десятка сюжетов для игр одновременно. Не считая тех, о которых забыл вчера.
* Когда [[Гораф]]у необходимо быстро написать новую игру, он просто выкидывает лишние сюжетные линии из какой-нибудь недописанной старой и выкладывает то, что получилось.
* Вредные привычки скрывает. Неженат.

==Игры==
===На URQ===
* [[Приключения Сары Фаерман: Мрачная тайна Катакомб Мрака]]
* [[Приключения Сары Фаерман: Темная тайна темного хлева]]
* [[Хроники капитана Блуда: Тайна левой ягодицы]] (серия "[[Капитан Блуд]]")
* [[Демоны темной стороны: Черный маг Ностромо]]
* [[Рисовая биржа]]
* [[Как видра, йожык и коъот бъолки памахали]] (серия "[[Видра, йожык и коъот|Видра]]")
* [[Адская суббота]]
* [[Трансмутация]]
* [[Как видра, йожык и коъот в хеллоууолк стирчали]] (серия "[[Видра, йожык и коъот|Видра]]")

===На QSP===
* [[1812]]
* [[Глод: Запах Зверя]]

===На RTADS===
* [[Хроники капитана Блуда: Тайна китайского чая со льдом]] (серия "[[Капитан Блуд]]")

===В соавторстве:===
* [[Рига]] ([[Goraph]] & [[KroL]])
* [[ЗИФ]] ([[Goraph]] & [[Евг]])
* [[Хроники капитана Блуда: Тайна гипсовых фаллоимитаторов]] ([[Goraph]] & [[Евг]]) (серия "[[Капитан Блуд]]")

==Любимые фразы (2004 года)==
*Да это просто задачка для [[Капитан Блуд|капитана Блуда]]...
*Это же сюжет для квеста!
*Вычеркните меня из соавторов!
*Вы все сфальсифицировали
*Мир захвачен транснациональными корпорациями
*Я, между прочим, говорил это абсолютно серьезно
*Я молод и стар
*Горокраксы

== Ссылки ==
[http://pavlenko.biz Сайт '''Горафа''']

[[Категория:Персоналии]]

Золотой Хомяк 2012

2013-06-13T14:35:31Z

Евг:

{| style="width:23em; font-size:90%; text-align:left; float:right; border:1px #CCC solid; margin-left:1em; margin-bottom:1em; border-collapse: collapse;" cellpadding="3" cellspacing="0"
! style="font-size:110%; text-align: center; background-color: #FDF3C4;" | [[Изображение:Homyak2012-fullsize.png|300px]]
|- style="border:1px #CCC solid;"
! Золотой Хомяк 2012
|}
Премия за достижения в интерактивной литературе на русском языке

----

== Регламент ==
Премия организована для определения лучших текстовых игр (interactive fiction) 2012 года.
В премии автоматически участвуют все текстовые игры, выпущенные с 1 января 2012 года по 31 декабря 2012 года.
Голосование проводится в следующих номинациях:
* Игра года
* Лучшие загадки
* Лучший сюжет
* Лучшая атмосфера
* Лучший литературный стиль новая
* Лучшие персонажи
* Лучшее оформление
* Проект года — проект, который был наиболее значимым в 2012 году.
Премию в конкретной номинации получает игра с наибольшим числом голосов по этой номинации. В случае одинакового числа максимальных голосов премию получат несколько игр сразу.
== Выбор публики ==
«Выбор публики» — результаты по всем голосам пользователей, проголосовавших на сайте премии.
Голосование публики проводится в два тура.
* Первый тур: в каждой номинации голосущий имеет право выбрать до трёх игр из всего списка, которые по его/её мнению достойны получить конкретную премию.
* Второй тур: голосующие выбирают в каждой номинации одну игру из 5-10 игр (в меньшую сторону) с наибольшим числов голосов. Жюри вправе выбрать, сколько игр выйдет во второй тур.
При голосовании рекомендуется написать комментарий, почему вы выбрали именно эту игру в конкретной номинации.
== Выбор жюри ==
«Выбор жюри» — результаты по голосам пользователей, являющимися членами жюри премии.
Голоса жюри подсчитываются отдельно от голосов других пользователей.
Члены жюри должны сыграть в каждую игру, за которую поступит хотя бы один голос пользователей.
После проведения премии голоса всех пользователей, включая голоса жюри, будут доступны для просмотра для зарегистрированных пользователей на сайте.
Сроки проведения:
* Первый тур: с 14 января по полночь с 26 на 27 января.
* Второй тур: с 28 января по полночь с 8 на 9 февраля. Тогда же оканчивается голосование жюри.
== Поощрения ==
Награждение будет проведено 10 февраля 2013 года в 20:00 по московскому времени на канале #ifrus сети irc.forestnet.org.
Голосовать нужно честно и объективно. Запрещается голосовать за свои игры и проекты.
Победитель в номинации «Игра года» по версии публики и победители во всех номинациях по версии жюри получат в подарок книгу-игру «Холодное сердце Далрока».
== Победители ==
'''Игра года''':
* Выбор публики: [[Драконы и принцессы]] ([[Morych]]; [[AXMA Story Maker]])
* Выбор жюри: [[Драконы и принцессы]] ([[Morych]]; [[AXMA Story Maker]])
'''Лучшие загадки''':
* Выбор публики: [[Гражданка Готье]] ([[Goraph]]; [[AXMA Story Maker]])
* Выбор жюри: [[Гражданка Готье]] ([[Goraph]]; [[AXMA Story Maker]])
'''Лучший сюжет''':
* Выбор публики: [[Драконы и принцессы]] ([[Morych]]; [[AXMA Story Maker]])
* Выбор жюри:
** [[Легенды всегда врут]] ([[Ulrick]]; [[AXMA Story Maker]])
** [[Деревянный город]] ([[Graf]]; [[Квестер]])
'''Лучшая атмосфера''':
* Выбор публики: [[Деревянный город]] ([[Graf]]; [[Квестер]])
* Выбор жюри: [[Двадцать желаний]] ([[April]]; [[AXMA Story Maker]])
'''Лучший литературный стиль''':
* Выбор публики: [[Приватир Её Величества]] ([[Cheshire]]; [[AXMA Story Maker]])
* Выбор жюри: [[Гражданка Готье]] ([[Goraph]]; [[AXMA Story Maker]])
'''Лучший персонаж''':
* Выбор публики: Нафанин из игры [[Почему в кладовке шум?]] ([[Серый Волк]]; [[URQ]])
* Выбор жюри: [[Глод]] из игры [[Глод: Запах Зверя]] ([[Goraph]]; [[QSP]])
'''Лучшее оформление''':
* Выбор публики: [[Дитя Луны]] ([[tangarou]]; [[Квестер]])
* Выбор жюри: [[Дитя Луны]] ([[tangarou]]; [[Квестер]])
'''Проект года''':
* Выбор публики: [[AXMA Story Maker]]
* Выбор жюри: [[AXMA Story Maker]]
== Статистика ==
По статистике из девяти игр попавших в финал пять сделаны на [[AXMA Story Maker]], две на [[Квестер]] и по одной на [[URQ]] и [[QSP]]
[[Изображение:Platform2012.png]]

== Ссылки ==

* [http://zh.ifiction.ru/ Оф. страничка]
* [http://zh.ifiction.ru/games Список игр]
* [http://zh.ifiction.ru/nominees Игры прошедшие во второй тур в голосовании публики]
* [http://zh.ifiction.ru/votes Расшифровка голосов]

[[Категория:Золотой хомяк]]

FireURQ:Особенности реализации URQL

2013-05-22T10:09:44Z

Евг: /* Ссылки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

В ссылках есть возможность использовать [http://ifwiki.ru/index.php?title=FireURQ:%D0%9E%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B5%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_URQL#.D0.9B.D0.BE.D0.BA.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D0.B4.D0.B5.D0.B9.D1.81.D1.82.D0.B2.D0.B8.D1.8F локальные действия] (действия, которые не уводят на другую локацию).

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-12T09:37:16Z

Евг: /* Ссылки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

'''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''<nowiki>[[%меню]]</nowiki>''' — модификатор на экран не выводится.

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:53:56Z

Евг: /* Ссылки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка". Можно добавлять модификаторы, например '''[[%меню]]''' — модификатор на экран не выводится.

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:48:42Z

Евг: /* Инклюды */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют.
* Каждый файл включается один раз. Другими словами, '''%include''' не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка".

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:47:08Z

Евг: /* Инклюды */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют. Только чистый текст, только хардкор. Комментарии тоже нельзя, к слову. Наверное, это временно.
*Каждый файл включается один раз. Другими словами, %include не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте. Данное поведение похоже на команду require в PHP.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
* Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка".

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:46:52Z

Евг: /* Инклюды */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют. Только чистый текст, только хардкор. Комментарии тоже нельзя, к слову. Наверное, это временно.
*Каждый файл включается один раз. Другими словами, %include не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте. Данное поведение похоже на команду require в PHP.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом '''mylib.qst''' вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка".

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:46:19Z

Евг:

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Инклюды==
Начиная с версии 1.8 в FURQ есть возможность «собирать» код игры из нескольких файлов. Для этого следует использовать макрос '''%include <имя_файла.qst>'''.
При этом действуют следующие правила:
* Макрос инклюда должен быть один на строке.
* Инклюды обрабатываются при загрузке квеста, поэтому подстановки там не действуют. Только чистый текст, только хардкор. Комментарии тоже нельзя, к слову. Наверное, это временно.
*Каждый файл включается один раз. Другими словами, %include не вставляет код из файла в то место, где он был вызван, а просто указывает, что этот код должен присутствовать в квесте. Данное поведение похоже на команду require в PHP.
* Имена меток и переменных сквозные. Следите, чтобы метки в разных файлах назывались по-разному.
Возможно использовать относительные пути, например '''%include inc\mylib.qst''', при этом путь указывается относительно того файла, в котором вызывается макрос. Т.е. если вы в вышеприведённом mylib.qst вызовете '''%include more\lowlevel.qst''', то '''lowlevel.qst''' должен лежать в папке '''inc\more\''', относительно главного файла квеста.
* Все ресурсы игры (картинки, музыка, шрифты) вызываются относительно главного файла квеста, в каких бы инклюдах и папках не находился код, их вызывающий.
* При упаковке в '''QSZ''' главный файл квеста должен называться''' main.qst''' или '''game.qst''' (qs1, qs2), чтобы интерпретатор понял, с чего начинать. Если FireURQ не найдёт такого файла в архиве, то вызовет первый попавшийся.

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка".

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:43:09Z

Евг: /* Ссылки */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте (и декораторах) ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:
'''[['''текст ссылки''']]'''
В данном случае ссылка будет вести на метку по названием "текст ссылки".

Пример:
'''pln''' Вдоль берега вьётся '''[['''тропинка''']]'''...

Здесь, при клике на ссылку произойдет переход на метку "тропинка".

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:38:36Z

Евг: /* Скрипты декораторов */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

Для команд col/colx, как и для '''decorcol''', если задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:35:00Z

Евг: /* Создание декораторов */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:33:48Z

Евг: /* Управление декораторами */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным. Если после имени декоратора задан один параметр — это цвет текста. Если два — это цвет текста и период времени, за который его надо поменять. Если три — это цвет текста, ссылки и подсветки. Если четыре — это три цвета и время, за которое они меняются.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T08:31:23Z

Евг: /* Переменные декораторов */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_linkcolor''' − позволяет задать цвет ссылок в декораторе.
*'''decor_имя_linkhcolor''' − позволяет задать цвет подсветки ссылки в декораторе.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]

FireURQ:Особенности реализации URQL

2013-04-04T07:55:28Z

Евг: /* Другое */

== Операции ==

* Есть оператор '''<>''' (не равно).
* Можно производить операцию сложения над строками. Т.е. можно сделать '''zz = xx + "urq"''' – и это будет работать, при условии, что '''xx''' — строковая переменная.
* Числовое представление строки — всегда число: длина этой строки. Это касается всех арифметических операций. Строковое представление числовой переменной — пустая строка (как в досурке).

==Подстановки (#...$ и #%...$)==
Работают только в пределах одного оператора. Т.е. вставить if с помощью подстановки — не получится, т.к. '''if...then...else''' — это конструкция языка, а не оператор.

==Параметры при переходах==
При переходах (операторы '''proc''', '''btn''' и '''goto''') возможно передать параметры на метку, на которую происходит переход.
''Синтаксис:''
'''goto <метка>[(param1, param2, ...)]'''
'''proc <метка>[(param1, param2, ...)]'''
'''btn <метка>[(param1, param2, ...)], <текст на кнопке>'''

В качестве параметров могут быть использованы любые выражения. Параметры при этом попадают в переменные '''<метка>_1''', '''<метка>_2''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> при использовании параметров в операторе btn подстановки ('''#...$''' и '''#%...$''') раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.</div>

''Пример:''
'''btn mylabel(2+2, "четыре"), Кнопка с параметрами'''
При нажатии на эту кнопку переменная '''mylabel_1''' примет числовое значение '''4''', а переменная '''mylabel_2''' — строковое значение '''"четыре"'''.

==Локальные действия==
Локальные действия, это действия не уводящие с локации. Т.е. можно сделать такую кнопку или ссылку, при нажатии на которую:
* не будут очищены кнопки
* не изменится переменная '''current_loc'''
* не выполнится '''common'''-локация

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

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

'''btn''' '''!'''local, Эта кнопка не уведёт с локации
'''pln''' Эта '''[['''ссылка|'''!'''local_location''']]''' тоже не уведёт с локации...

==Музыка и звук==
'''FireURQ''' поддерживает множество форматов музыки и звука. Командой '''play''' можно воспроизводить звуки. Музыка воспроизводится командой '''music'''.
===Звуки===

'''play [loop|stop] [<имя файла>[, <громкость>]]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG

'''громкость''' – может принимать значения от '''0''' до '''255'''

Если указать параметр '''loop''', то воспроизведение звука будет зациклено (полезно, если нужно реализовать фоновый эмбиентный звук). Если указан параметр '''stop''', то конкретный звук (все его «ипостаси», если воспроизведение конкретного звука было запущено несколько раз) будет остановлен. Если указать stop и не указать имя файла, то будут остановлены все звуки.

===Музыка===

'''music <имя файла>|stop[, <время в миллисекундах>]'''
'''имя файла''' – это имя файла формата WAV/AIFF/MP3/MP2/MP1/OGG, плюс форматы трекерной музыки: XM, IT, S3M, MOD, MTM, UMX. Кроме того, воспроизводится и MIDI-музыка (файлы MID). Также поддерживается формат MO3 (трекерная музыка с OGG-упакованными семплами). Конвертер для превращения любого трекерного формата в MO3 можно скачать с сайта http://un4seen.com/.

Если требуется остановить воспроизведение, то вместо имени файла указывается '''stop'''.

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

Для регулировки громкости музыки используется переменная '''music_volume''', которая может принимать значения от '''0''' до '''255'''.

Возможно плавное изменение громкости музыки командой '''fademusic''':
'''fademusic <громкость>, <время в миллисекундах>'''

'''громкость''' – целевая громкость музыки.

'''время в миллисекундах''' – время, в течении которого громкость достигнет целевого значения.
Кроме того, для музыки поддерживается переменная '''music_looped''', которая принимает два значения: '''1''' и '''0'''. Эта переменная указывает, будет ли воспроизводимая музыка зациклена или проиграет один раз и остановится. По умолчанию равна '''1''' (музыка зацикливается).

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.</div>

===Озвучка локаций===

'''voice <имя файла>'''
'''voice stop'''
С помощью команды '''voice''' можно удобно озвучивать локации в квестах. Действие этой команды аналогично действию команды '''play''' – проигрывается звук, указанный в качестве параметра, за несколькими исключениями:
* Озвучка может быть только одна в любой момент времени. Каждая следующая команда '''voice''' останавливает предыдущую;
* Переход по кнопке ('''btn''') также останавливает озвучку.
* Громкость озвучки регулируется с помощью переменной '''voice_volume''', а не указывается напрямую в команде.

==Изображения==

'''FireURQ''' позволяет вставлять изображения в текст квеста. Для этого служит команда '''image'''.
'''Синтаксис:'''
'''image <имя файла>[, X, Y, ширина, высота]'''
* '''имя файла''' – это имя файла изображения в формате JPEG, PNG или TGA.
* Дополнительные параметры позволяют вывести не все изображение, а его часть. При этом '''X''' и '''Y''' задают верхний левый угол окна, а ширина и высота – размеры «вырезаемого» кусочка.

Изображение вставляются в текст и ведут себя как обычные буквы. Альфа для вставляемого изображения берется из цвета текста (переменная '''textcolor ''' – см. ниже).
==Текст==
===Выравнивание текста===

'''FireURQ''' позволяет выравнивать текст влево, вправо или по центру. Для установки нужного режима выравнивания текста служит переменная '''textalign'''. Она может принимать следующие значения:
* '''1''' – текст выравнивается влево
* '''2''' – текст выравнивается вправо
* '''3''' – текст выравнивается по центру
Естественно, выравнивание работает лишь внутри одного «абзаца». Если вы выводили текст командой '''print''' (без переноса), затем сменили выравнивание и попытались что-то вывести в той же строке, то текст с другим выравниванием будет перенесен на другую строку автоматически.
Переменная '''btnalign''' позволяет выровнять кнопки действия. А '''btntxtalign''' – текст внутри кнопок (т.е. надписи на кнопках). Следует отметить, что выравнивание кнопок работает только для всех кнопок скопом. Т.е. не получится выровнять одну кнопу вправо, а другую – влево.

Расстояние между строками и параграфами определяется следующими системными переменными:
* '''linespacing''' – вертикальное расстояние между строк текста (по умолчанию '''3''')
* '''paraspacing''' – вертикальное расстояние между параграфами (по умолчанию '''3''')

===Цвет текста===
Для определения цвета выводимого текста служит переменная '''textcolor'''. Цвет в '''FireURQ''' задается шестнадцатиричным числом в формате 0xAARRGGBB. То есть четыре составляющих: альфа, красный, зеленый и синий. При этом альфу можно опускать, т.е. цвет '''0xFF7F05BB''' и '''0x7F05BB''' – равнозначны. Также, для обратной совместимости поддерживается переменная '''Style_dos_textcolor''', которая работает так же, как и в '''DOS_URQ'''. Цвет фона менять нельзя, только цвет букв.

===Шрифт текста===

Для определения шрифта, которым будет выводиться текст, используется переменная textfont. В нее в виде строкового значения следует записать имя файла шрифта. FireURQ может использовать растровые шрифты формата HGE Font (заимствовано из библиотеки HGE). Редактор, позволяющий конвертировать шрифты, установленные в Windows, в формат HGE Font, входит в дистрибутив (папка '''fonted''').

Чтобы вернуться к шрифту по умолчанию, следует выполнить '''textfont = "_sysfont"'''.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.</div>

TrueType шрифты используются так:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"'''
*'''size''' – размер шрифта(по умолчанию '''19''')
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')
Параметры можно опускать.

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в '''bgcolor'''. '''Gamma''' и '''weight''' по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.</div>

'''''Примеры:'''''
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''
Файлы TrueType шрифтов (.ttf) ищутся сначала в папке игры (в архиве '''QSZ'''), а если их там нет, то в системной папке со шрифтами Windows. Т.е. если это системный шрифт, прикладывать его к игре не нужно.

Шрифты таким образом можно использовать как в коде игры, так и в [[FireURQ:Скины|скинах]].

===Ссылки===

Начиная с версии 1.6 '''FireURQ''' позволяет использовать в тексте ссылки.

Формат ссылок:
'''[['''текст ссылки'''|'''название локации''']]'''

Пример:
'''pln''' Вы стоите на берегу реки. Вдоль берега вьётся небольшая '''[['''тропинка'''|'''trop''']]'''...

Здесь '''trop''' - название локации, на которую будет осуществлён переход при нажатию на ссылку. Разумеется, как и в '''btn''', можно использовать параметры локации.

Цвет ссылок задаётся переменными '''linkcolor''' и '''linkhcolor'''. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши. Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

===Выпадающие меню===
Начиная с версии 1.6 в '''FireURQ''' появилась возможность использовать меню, выпадающие при клике на ссылку или на кнопку . Меню формируются точно так же как обычные ссылки или кнопки с использованием символа '''%''' и могут быть любого уровня вложенности.

Общий синтаксис такой:
btn '''%'''<Название локации>, <Текст на кнопке>
[[ <Текст ссылки> | '''%'''<Название локации>]]

'''Пример'''
'''btn''' '''%'''menu, По этой кнопке будет меню

''':menu'''
'''btn''' someloc, Первый пункт меню
'''btn''' anotherloc, Второй пункт меню
'''btn''' yetonemoreloc, Третий пункт меню
'''end'''

Все кнопки в меню-локации превращаются в пункты меню. В меню-локациях не разрешается использовать практически ничего, кроме конструкций '''if..then..else'''', '''goto''', '''proc''', '''btn''' и работы с переменными, которые можно назначать и проверять. Все фантомные '''btn''' (ведущие на несуществующую локацию) становятся неактивными пунктами меню.

Если в качестве имени кнопки использовать "-" (дефис), то в меню будет вставлена полоска-разделитель.

Переменные для оформления меню (их тоже можно указывать прямо в меню-локации):

'''menu_textfont''' - шрифт меню
'''menu_bgcolor''' - цвет фона (можно делать и полупрозрачным)
'''menu_bordercolor''' - цвет рамки
'''menu_textcolor''' - цвет пунктов меню
'''menu_hindent''' - отбивка по горизонтали
'''menu_vindent''' - отбивка по вертикали
'''menu_selectioncolor''' - цвет фона выбранного элемента
'''menu_seltextcolor''' - цвет шрифта выбранного элемента
'''menu_disabledcolor''' - цвет шрифта неактивного элемента

==Декораторы==
Декораторы – это небольшие кусочки текста или графические объекты, которые можно поместить в любое место на экране. Декораторами можно управлять, например плавно перемещать или менять оттенок цвета. Графическим декоратором можно дополнительно изменять масштаб, угол наклона, скорость вращения и другие параметры. С помощью декораторов автор может лучше оформить квест, вывести дополнительные параметры или добавить анимационные эффекты.

===Создание декораторов===

Общий синтаксис для добавления декоратора следующий:

'''decoradd <имя> (<x>,<y>[, <z>]) <тип декоратора> <параметры>'''

*'''имя''' – имя декоратора, состоящее из цифр, букв и знаков подчеркивания. Пробелы в имени не допускаются.
*'''x''', '''y''' и '''z''' – координаты декоратора на экране. Параметр '''z''' используется для определения «глубины» декоратора. Чем меньше '''z''', тем «ближе» декоратор к игроку. Все декораторы с '''z''' от 0 и больше располагаются «за» интерфейсом (кнопки управления и текстовое поле), а с '''z''' меньше 0 – «перед» ним. Если '''z''' не указан, то он принимается равным 0.
*тип декоратора может быть '''TEXT''', '''RECT''', '''IMAGE''', '''ANIMATION''' и '''GIF'''.
*'''параметры''' – разные, в зависимости от типа декоратора.

Теперь более подробно по типам.

Тип '''TEXT''' позволяет добавить декоратор-кусочек текста:

'''decoradd <имя> (<x>,<y>[, <z>]) TEXT "собственно, текст" [, цвет[,"шрифт"]]'''

Если '''цвет''' или '''шрифт''' не указаны, то они принимаются равными цвету и шрифту основного текста.

Тип '''RECT''' – это просто цветной прямоугольник:

'''decoradd <имя> (<x>,<y>[, <z>]) RECT ширина, высота [, цвет]'''

Если '''цвет''' не указан, то он принимается равным цвету основного текста.

Тип '''IMAGE''' – это декоратор-картинка. Параметры этого декоратора очень похожи на параметры оператора '''image''' (см. выше) :

'''decoradd <имя> (<x>,<y>[, <z>]) IMAGE "имя_файла"[, X, Y, ширина, высота]'''

Как и в операторе '''image''' , дополнительные параметры позволяют вывести лишь часть картинки. Если у вас много аниматоров-картинок, то, в целях быстродействия, рекомендуется размещать их на одном «полотне», а не загружать из разных файлов.

Декоратор-анимация добавляется с помощью типа '''ANIMATION''' :

'''decoradd <имя> (<x>,<y>[, <z>]) ANIMATION "имя_файла", X, Y, ширина, высота, N'''

'''Х''' и '''Y''' это координаты первого кадра анимации (левый верхний угол). Параметры похожи на параметры типа '''IMAGE''', за исключением того, что здесь параметры, определяющие кадр, опускать нельзя. '''N''' определяет количество кадров в анимации. Кадры должны располагаться на картинке один за другим, слева направо и сверху вниз (если они не помещаются на картинке в одну строку).

Декоратор-GIF можно создать с помощью типа '''GIF''':

'''decoradd <имя> (<x>,<y>[, <z>]) GIF "имя_gif-файла"'''

<div style="background-color:LavenderBlush;padding:5px;border:1px solid Brown;"><font color="maroon">'''Важное замечание:'''</font> В декораторах типа '''IMAGE''' можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом '''GIF'''. </div>

===Управление декораторами===

Для управления декораторами применяются следующие команды:

'''decormov <имя> X, Y[, время]'''
Позволяет переместить декоратор в точку с координатами '''X''' и '''Y'''. Если указано '''время''' (в миллисекундах), то перемещение будет плавным и займет как раз указанное время.

'''decorcol <имя> цвет[, время]'''
Позволяет установить цвет декоратора. Если указано '''время''', то изменение цвета будет плавным.

'''decorrot <имя> угол[, время]'''
Позволяет повернуть декоратор на определенный '''угол''' (в градусах). Важно помнить, что угол в этой команде задается ''относительно текущего''. Это позволяет поворачивать декоратор в обе стороны. Если указано '''время''', то поворот будет плавным. Эта команда не работает с декораторами типа '''TEXT'''.

'''decordel [<имя1>, <имя2>, …]'''
Удаляет перечисленные в параметрах декораторы. Без параметров удаляет все декораторы.

'''decorscl <имя> масштаб[, время]'''
Позволяет установить '''масштаб''' декоратора. Масштаб задаётся дробным числом. Масштаб, равный 2 - это двойной размер декоратора, а 0.5 - половинный. Если указано '''время''', то изменение цвета будет плавным.

'''decorscr <имя> "скрипт"'''
Назначает декоратору скрипт.

===Маски имён===
Во всех командах управления декораторами в качестве параметра '''имя''' можно передавать маску имён с использованием символов '''*''' (замещает любое количество символов) и '''?''' (замещает один символ). Например, команда
'''decorrot sas* 90, 2000'''
повернёт все декораторы, имя которых начинается с "sas", на 90 градусов по часовой стрелке за две секунды.

===Переменные декораторов===
Разнообразные параметры декораторов можно устанавливать с помощью специальных переменных. Эти переменные начинаются на decor_ , после чего следует имя декоратора. Переменные бывают следующих типов:
*'''decor_имя_x, decor_имя_y и decor_имя_z''' – позволяют задать координаты декоратора.
*'''decor_имя_color''' – позволяет задать цвет декоратора.
*'''decor_имя_hide''' – если установлен в 1, то декоратор скрыт.
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора(в пикселях), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''), по умолчанию равна 2000000000
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_angle''' – позволяет задать угол поворота декоратора (кроме типа '''TEXT'''). Угол задается в градусах.
*'''decor_имя_rotspeed''' – позволяет задать постоянную скорость вращения декоратора (кроме типа '''TEXT'''). Скорость задается в градусах в секунду и может иметь как положительное, так и отрицательное значение.
*'''decor_имя_scale''' – позволяет задать масштаб декоратора (кроме типа '''TEXT'''). По умолчанию равна 1.
*'''decor_имя_frame''' – позволяет задать текущий кадр анимации (только для типов '''ANIMATION''' и '''GIF'''). Процесс анимации при этом останавливается.
*'''decor_имя_anispeed''' – позволяет задать скорость анимации (только для типов '''ANIMATION''' и '''GIF'''). Для разных типов поведение различается:
**Для типа '''ANIMATION''' . Если анимация остановлена, то равна 0. Обозначает задержку в миллисекундах между сменой кадров. Может принимать как положительное, так и отрицательное значение. По умолчанию имеет значение 250;
**Для типа '''GIF''' . Если анимация остановлена, то равна 0. Обозначает процент от скорости, записанной в самом GIF-файле. Может принимать значения от 0 до 1000. По умолчанию имеет значение 100.
*'''decor_имя_anitype''' – позволяет задать тип анимации (только для типа '''ANIMATION'''). Может принимать следующие значения:
**'''0''' – анимация проигрывается один раз и останавливается;
**'''1''' – анимация зациклена (с последнего кадра перескакивает обратно на первый);
**'''2''' – анимация зациклена в режиме «пинг-понг» (при достижении граничного кадра меняется направление анимации).
*'''decor_имя_script''' – позволяет задать скрипт декоратора. Прочитать значение переменной скрипта нельзя, его можно только назначить.
*'''decor_name_linespacing''' - вертикальное расстояние между строк текста (только для '''TEXT'''). По умолчанию равно системному '''linespacing'''.
*'''decor_name_paraspacing''' - вертикальное расстояние между параграфами (только для '''TEXT'''). По умолчанию равно системному '''paraspacing'''.

===Скрипты декораторов===
Скрипты позволяют "запрограммировать" декоратор. Другими словами, назначить ему последовательность команд по перемещению, вращению, изменению масштаба и т.д., которые декоратор будет выполнять самостоятельно, не требуя дополнительного команд в коде игры. Эта функция удобна, когда вам надо реализовать системы частиц (снежинки, дым) для оформления вашей игры, или просто добавить визуальных эффектов.

Скрипты декораторам назначаются с помощью команды '''decorscr''' или переменной '''decor_имя_script''' и представляют собой строку, содержащую последовательность команд, разделённых символом косой черты ('''/''').

'''''Команды'''''

'''mov x, y [, time]''' - перемещение в точку '''x''', '''y''' (опционально - за время '''time''')

'''mvr''' - то же самое, но координаты задаются относительные

'''movx''' и '''mvrx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''pau <time>''' - пауза на время '''time'''

'''col <цвет>[, time]''' - изменение цвета декоратора (опционально - за время '''time''')

'''col <A, R, G, B>[, time]''' - то же самое, но компоненты цвета задаются отдельными параметрами

'''colx''' - то же самое, но следующая команда выполнится немедленно (не будет паузы на время '''time''')

'''ang <угол>''' - задать абсолютный угол поворота декоратора (в градусах)

'''rot <угол>[, time]''' - поворот декоратора на угол (относительное значение, опционально - за время '''time''')

'''rotx''' - без паузы

'''rsp <скорость вращения>''' - позволяет задать скорость вращения (положительную или отрицательную, в углах в секунду)

'''scl <масштаб>[, time]''' - задать масштаб декоратора (опционально - за время '''time''')

'''sclx''' - то же самое без паузы

'''rst''' - запустить скрипт с начала

'''del''' - уничтожить декоратор

'''''Случайные параметры'''''

Любой из параметров можно определить как '''R(min,max)''', таким образом, при исполнении команды будет вычислено случайное значение от '''min''' до '''max'''.

'''''Пример'''''
'''decorscr star "mvr 50, 0, 1000/rot R(-90,90), 1500/rst"'''
Декоратор с именем '''star''' переместится вправо на 50 пикселей за одну секунду, затем повернётся на случайный угол от -90 до 90 градусов (т.е. вправо или влево) за полторы секунды и начнёт выполнять скрипт сначала, то есть будет продолжать двигаться вправо и поворачиваться, уезжая за правую границу экрана.

==Скины==

Скин игры - это файл с описанием того, как должен выглядеть интерпретатор FireURQ при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в [[FireURQ:Скины|отдельном разделе]].

== Формат квестов QSZ==

'''FireURQ''' поддерживает свой собственный формат квеста – упакованный квест ('''QST Zipped'''). '''QSZ'''-файл – это, по сути, zip-архив, в котором лежит сам файл квеста ('''qst''', '''qs1''' или '''qs2''') и все ресурсы, необходимые для работы игры (изображения и музыка). Данный формат очень удобен, если ваша игра использует мультимедиа.

Также, существует возможность конвертации квеста в формате QSZ в исполняемый файл. Для этого следует использовать утилиту '''QSZ2EXE''', которая входит в комплект поставки. Эта консольная утилита находится в папке на диске, которую вы выбрали при инсталляции '''FireURQ'''.

== Режим отладки ==

Режим отладки включается с помощью ключа '''-d''' в командной строке. При включенном режиме отладки все ошибки в коде квеста выводятся прямо в текст. Кроме того, в режиме отладки работает полезная комбинация '''Ctrl+R''', позволяющая перезагрузить исходный текст квеста с диска. Происходит сохранение игры, перезагрузка исходного текста и загрузка сохраненного состояния с переходом на ту же локацию, что и до перезагрузки. Это позволяет править исходный текст и сразу же смотреть результаты изменений.

==Инвентарь==

Существует возможность скрывать действия над предметами. Для этого необходимо использовать специальные переменные. Имя переменной формируется как имя локации-действия над предметом инвентаря, плюс «'''_hide'''». Например, если выполнить '''Use_Топор_Рубить дерево_hide = 1''', то действие “Рубить дерево» у предмета инвентаря «Топор» будет скрыто до тех пор, пока вы не присвоите этой же переменной значение '''0'''.

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

Также возможно поменять отображение предмета в списке инвентаря. Для этого используются переменные вида '''idisp_предмет''', например:
'''idisp_Бутылка = "Бутылка с водой"'''
При этом важно понимать, что '''idisp_-переменные''' влияют только на отображение предмета в списке инвентаря. В операторах '''inv+''' и '''inv-''', а также при обращении к счетчикам предметов через '''inv_-переменные''', следует использовать изначальное название («Бутылка» в примере):
'''inv- Бутылка'''
'''if inv_Бутылка > 1 then pln У вас несколько бутылок…'''

==Предопределенные функции==

В '''FireURQ''' предусмотрены предопределенные функции, которые вызываются с помощью оператора proc. Результат возвращается в переменной '''_result'''. Существуют следующие предопределенные функции:

'''_sin(x)''', '''_cos(x)''' и '''_tan(x)''' – позволяют вычислить соответственно синус, косинус и тангенс числа x, представленного в радианах.

'''_color([a,] r, g, b)''' – позволяет получить значение цвета из его составляющих. Если составляющая прозрачности ('''a''') не указана, то она принимается равной '''255'''(т.е. полностью видимый цвет).

'''''Пример:'''''
'''proc _color(x+15, 10, 255, 60)'''
'''textcolor = _result'''

==Anykey==

'''anykey [<переменная>[, <pause>]]'''

По команде '''anykey''' игра приостанавливается и ждёт нажатия на клавишу. Если указана переменная, то код клавиши будет записан в неё. При нажатии на функциональную клавишу в '''anykey''' возвращается скан-код этой клавиши, а переменная '''is_syskey''' устанавливается в '''1'''. Состояние клавиш '''Shift''', '''Ctrl''' и '''Alt''' на скан-коде функциональной клавиши не отражаются.

Также, у команды '''anykey''' существует возможность задавать таймаут. Например, по команде '''anykey z, 1000''' игра секунду будет ожидать нажатия кнопки, а если за секунду кнопка нажата не будет, то игра продолжит выполнение, а в переменную '''z''' будет записан ноль.

При использовании команды '''anykey''' нажатия на кнопку мыши тоже расцениваются как нажатия на клавишу, при этом в переданную переменную записываются коды '''256''', '''257''' и '''258''' для левой, правой и средней кнопок соответственно, а в переменные '''mouse_x''' и '''mouse_y''' – координаты, в которых был сделан клик.

==Слоты сохранений==

В '''FURQ''' предусмотрено сохранение состояния игры в слоты ('''7''' обычных слотов и слот “автосохранения”).

'''save <локация>''' - записывает сохранение в слот автосохранения.

'''save <локация>, "имя сохранения"''' - запускает интерфейс со слотами, дает выбрать слот сохранения (кроме слота “автосейва”) и записывает в него сохранение с указанным именем.

'''save <локация>, "имя сохранения", <номер слота>''' - запишет сохранение в указанный слот, где номер слота - число от '''0''' до '''7''' ('''0''' - слот автосохранения).

'''''Пример:'''''

'''save location; записать в слот автосохранения'''
'''save location, “Сохранение”; записать в любой слот, который выберет игрок'''
'''save location, “Мой автосейв”, 0; записать в слот автосохранения'''
'''save location, “Утро, Румыния, 17-й век”, 5; записать в пятый слот'''

Загрузка сохранения происходит путем выбора пункта меню '''"Загрузить сохранённую игру"'''. При этом если есть только автосейв - он загружается сразу, если же кроме автосейва занят какой-нибудь слот - выдается интерфейс выбора из слотов.

== Другое ==

* '''count_...''' — переменные счетчики обновляются ТОЛЬКО при переходах по '''btn'''. Старое поведение '''URQ_DOS''', когда '''count_...''' увеличивается и по '''proc''' и по '''goto''', можно включить, установив переменную dosurq_count в '''1'''.
* Переход по действиям в инвентаре не перезапускает локацию заново при возврате. Если действие было вызвано во время '''end''' — то происходит безусловный переход ('''goto''') на локацию-действие. Если же вы решили использовать инвентарь во время pause, то локация-действие вызывается как '''proc''' с возвратом на оператор, следующий за pause. Долго думал над этим поведением и решил, что так будет правильнее всего.
* Есть переменная '''gametitle''' — позволяет вывести название игры в заголовок окна. По умолчанию там имя файла, из которого игра была загружена.
* Ключ '''-l''' командной строки позволяет направить весь вывод в файл, т.е. создавать логии прохождений. Файлы логов будут называться '''имяквеста.000.log''', '''имяквеста.001.log''' и т.д.
* Клавиатурные шорткаты для системного меню и инвентаря – клавиши ['''Esc'''] и ['''I'''], соответственно.
* Имеется возможность включить полноэкранный режим, нажав сочетание клавиш '''Alt+Enter'''. Повторное нажатие Alt+Enter выключает полноэкранный режим.
* Можно прокручивать экран с помощью клавиш '''PgUp''' и '''PgDown''', а также колесом мыши. Если держать '''Ctrl''', то колесо мыши прокручивает экран маленькими порциями.
* В оператор '''tokens''' можно передавать не только строковую переменную, но и просто строку, заключенную в кавычки или строковое выражение.
* Индикацию состояний ожидания (мигающая иконка в углу экрана) при выполнении операторов anykey, pause и при требуемой прокрутке текста можно отменить с помощью переменных '''hide_anykey_indicator''', '''hide_pause_indicator''' и '''hide_more_indicator''', присвоив им значение '''1'''.
* Есть возможность изменять положение и размер главного текстового поля. Для этого служат переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height'''.
* Скрыть «эхо» выполняемых действий при нажатии кнопки, использовании инвентаря и сохранении игры возможно с помощью переменных '''hide_btn_echo''', '''hide_inv_echo''' и '''hide_save_echo''', соответственно, установив их в '''1'''.
* Переменная '''hide_link_echo''' скрывает «эхо» от ссылок, если её установить в '''1'''.
* Переменная '''hide_local_echo''' скывает «эхо» от локальных действий, если её установить в '''1'''. По умолчанию равна '''1'''.
* При сохранении игры командой '''SAVE''' переменная '''save_success''' устанавливается в '''1''' при успешном сохранении и в '''0''', если сохранение по каким-то причинам не удалось.
* Если установить переменную '''numbuttons''' в '''1''', то кнопки действий будут пронумерованы, а нажатие цифровых клавиш на клавиатуре будет приводить к нажатию соответствующей кнопки.
* Переменные '''mouse_x''' и '''mouse_y''' возвращают текущие координаты мыши на момент вызова.
* При нажатии '''Ctrl+C''' в буфер обмена будет помещён текст последней локации.
* Команда '''CLSL''' делает неактивными все ссылки в тексте.
* Переменная '''inventory_enabled''' (по умолчанию '''1''') отвечает за доступность инвентаря, при значении '''0''' инвентарь недоступен и наоборот.

[[Категория:Документация FireURQ]]