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

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

2017-05-01T12:09:54Z

CHameleon: /* Подстановки (#...$ и #%...$) */

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

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

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

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. [http://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''' и так далее. Все старые значения "переменных с параметрами" — удаляются (даже если в прошлый раз было больше параметров).
Возможен максимум - 50 параметров.

<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''' Эта '''<nowiki>[[</nowiki>'''ссылка|'''!'''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''')

'''''Пример:'''''
'''textalign = 1'''
'''btnalign = 3'''
'''btntxtalign = 3'''
Этот код выведет последующий текст с выравниванием влево, а кнопки - посередине, так же посередине будет располагаться и текст в кнопках.

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

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

Для определения шрифта, которым будет выводиться текст, используется переменная 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]"'''

'''''Пример использования в игре:'''''
'''textfont = "georgia.ttf[18, 1.0, 0.1, 0x000000]"'''
Такой шрифт идеально подойдёт для светлых фонов

Файлы TrueType шрифтов (.ttf) должны лежать в папке игры (в архиве '''QSZ'''). Если их там нет, то игра возьмёт системный шрифт для текста по умолчанию.

Фурка носит с собой шрифты стандартных начертаний с засечками ('''serif''') и без засечек ('''sans''') трёх начертаний- обычной, полужирной ('''bold''') и наклонной ('''italic'''). Эти стандартные шрифты можно использовать, подставляя вместо имени файла TTF название, комбинирующее нужное начертание шрифта. Например,
'''textfont = "serif[35]"'''
это шрифт с засечками 35-го размера. А
'''textfont = "sans-bold-italic[18]"'''
это полужирный наклонный шрифт без засечек 18-го размера.

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

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

'''''Пример:'''''
Можно написать без параметров:
'''btn лес,Войти в лес'''
а можно добавить параметры:
'''btn лес(1,"опушка"),Войти в лес'''
В обоих случаях этот код сделает кнопку с надписью '''Войти в лес''', ведущую на локацию '''лес'''
но во втором варианте, на локации лес, переменные '''лес_1''' и '''лес_2''' будут соответссвенно равны '''1''' и '''опушка'''
то есть, если мы напишем код:
''':лес'''
'''pln #лес_1$ и #%лес_2$'''
'''end'''
то в результате, при переходе по кнопке, увидим на экране:
'''1 и опушка'''
Это очень удобно для организации проверок внутри локации.

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

'''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''' - цвет шрифта неактивного элемента

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

*'''bmenualign''' отвечает за положение меню относительно кнопок '''btn'''
*'''lmenualign''' отвечает за положение меню относительно ссылки.
*'''decor_имя_menualign''' отвечает за положение меню относительно декоратора.

Эти переменные содержат строку из двух букв. Первая буква — это положение относительно объекта (кнопки или ссылки), вторая — выравнивание.

'''Пример'''
'''bmenualign = «RB»'''
меню относительно кнопок будет справа (Right) и выровнено по нижнему (Bottom) краю.

Значение для меню берётся из сочетаний первых букв положений: Top (верх), Bottom (низ), Center (центр), Left (лево), Right (право).

Значения по умолчани.
* для кнопок - «TL»
* для ссылок — «RL»

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

С версии 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''', '''TEXTBUTTON''', '''IMGBUTTON''' и '''CLICKAREA'''.
*'''параметры''' – разные, в зависимости от типа декоратора.
Команда '''decoradd''' позволяет задать от одного до трёх цветов для текстового декоратора.

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

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

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

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

'''''Пример:'''''
'''decoradd добро_пожаловать (0,0, -1) TEXT "Добро пожаловать в игру", 0xFF990033, "georgiab.ttf[22]"'''
этот декоратор выведет текст - '''Добро пожаловать в игру''' с позиции '''0,0''' в окне,
с непрозрачным цветом '''990033''' и шрифтом '''georgia''' жирный '''22''' размера,
располагающийся перед основным текстом и перекрывающий его

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

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

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

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

'''''Пример:'''''
'''decoradd кнопка (10,100, -1) TEXTBUTTON "mybutton", "Благодарности", "об_игре"'''
в данном примере мы имеем кнопку с определённой в скине рамкой '''mybutton''', с надписью '''Благодарности''',
расположенную в позиции '''10,100''' экрана и ведущую в локацию '''об_игре''',
располагающуюся перед основным текстом и перекрывающую его

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

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

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

'''''Пример:'''''
'''decoradd квадрат (10,10, -1) RECT 300, 300, 0xFF990033'''
этот декоратор нарисует квадрат с позиции '''10,10''' в окне, шириной и высотой в '''300''' пикселей
с непрозрачным цветом '''990033''', располагающийся перед основным текстом и перекрывающий его

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

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

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

'''''Пример:'''''
'''decoradd область_клика (50,50, -1) CLICKAREA 200, 50, "переход"'''
этот декоратор выведет прямоугольную область на экране в позиции '''50,50''' окна, шириной '''250''' и высотой '''50''',
располагающуюся перед основным текстом и перекрывающую его, кликнув на которую, мы попадём в локацию '''переход'''

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

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

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

'''''Пример:'''''
'''decoradd бэкграунд (0,0, 2) IMAGE "back.png", 0, 0, 1024, 768'''
этот декоратор выведет картинку из файла '''back.png''' на экран в позиции '''0,0''' окна, шириной '''1024''' и высотой '''768''',
располагающуюся за основным текстом

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

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

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

'''''Пример:'''''
'''decoradd моя_кнопка (50,50, -1) IMGBUTTON "button.png", 0, 0, 100, 50, "лес"'''
этот декоратор выведет на экран внопку в позиции '''50,50''' с текстурой из файла '''button.pn''',
определив начальную картинку из текстуры с позиции '''0,0''' шириной '''100''' и высотой '''50''' пикселей,
располагающуюся перед основным текстом. При нажатии на кнопку осуществится переход на локацию с названием '''лес'''.

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

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

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

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

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

'''''Пример:'''''
'''decoradd анимация_героя (50,50, -2) ANIMATION "anime.png", 0, 0, 200, 400, 20'''
этот декоратор покажет на экране анимацию из файла текстуры '''anime.png''', в позиции '''50,50''' окна,
шириной кадра '''200''' и высотой '''400''', состоящую из '''20''' кадров и располагающуюся перед основным текстом

Декоратор-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>

'''''Пример:'''''
'''decoradd гиф_картинка (50,50, -1) GIF "anime.gif"'''
этот декоратор покажет анимированную gif картинку из файла '''anime.gif''' на экране в позиции '''50,50''',
располагающуюся перед основным текстом

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

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

'''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 или IMGBUTTON неактивен (нельзя нажать). Для декораторов типа TEXT, если равен 0, отключает все ссылки находящиеся в них.
*'''decor_имя_target''' - позволяет устанавливать имя "целевой локации", если такая используется в декораторе
*'''decor_имя_text''' – устанавливает текст декоратора (только для типа '''TEXT''')
*'''decor_имя_align''' – устанавливает тип выравнивание текста внутри декоратора аналогично переменной '''textalign''' (только для типа '''TEXT'''), по умолчанию равна 1
*'''decor_имя_width''' – возвращает ширину декоратора (масштабируется по ширине текста в нём), устанавливает ширину текстового декоратора, по которой текст будет переноситься на другую строку (только для типа '''TEXT'''). Чтобы вернуться к автомасштабированию, достаточно присвоить переменной decor_имя_width значение ноль.
*'''decor_имя_height''' - возвращает высоту декоратора (в пикселях).
*'''decor_имя_hotx''' и '''decor_имя_hoty''' – позволяют задать «горячую точку» для декоратора (кроме типа '''TEXT'''). Горячая точка задается в пространстве самого декоратора (по умолчанию – 0,0) и служит для привязки. Предположим, у вас изображение размером 25х25 пикселей. Если вы установите горячую точку в (13, 13), то, при вращении декоратора, вращение будет происходить вокруг центра картинки. Так же и при позиционировании на экране привязка будет за центр картинки.
*'''decor_имя_flipx''' и '''decor_имя_flipy''' - позволяет задать горизонтальный и вертикальный флип (зеркальное отображение) для декораторов-картинок. Если переменные равны 1, то картинка отображается зеркально по оси x или y соответственно.
*'''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'''. Существуют следующие предопределенные функции:

Функция '''_int''' отбрасывает дробную часть числа. Если вызвать, например, proc _int(3.14), то в переменной _result окажется 3.

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

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

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

'''_power(w, n)''' - вычисление степени числа. Здесь два параметра — основа и значение степени. Если оставить только x, он будет возведён в квадрат. Также, вспомнив школьный курс алгебры, с помощью '''_power''' можно извлекать корни любой степени.

'''_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''' – координаты, в которых был сделан клик.

'''''Пример:'''''
'''anykey z, 1000'''

==Time==

С версии 2.0 появилась переменная '''time''', которая хранит в себе количество миллисекунд, прошедших с момента загрузки Windows. Это удобно, если надо засечь время реакции игрока.

==Mousecursor==

С версии 2.0 появилась возможность кастомизировать курсор. Им теперь может служить любой декоратор. Достаточно присвоить имя этого декоратора переменной '''mousecursor'''. При этом точка привязки декоратора становится точкой указания для мыши. Чтобы вернуться к системному курсору, нужно присвоить переменной '''mousecursor''' пустое значение. При этом декоратор тоже нужно уничтожить, иначе он останется на экране.

'''''Пример:'''''
'''decoradd cursor (0,0, 50) IMAGE "arrow.png"'''
'''mousecursor = "cursor"'''

==Сохранение игры и оператор SAVE==

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

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

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

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

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

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

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

С версии 2.0 '''FURQ''' сохраняет полное состояние игры на момент сохранения и способна вернуться в ту точку кода, где была вызвана команда SAVE. То есть, после загрузки, выполнение продолжится с команды, следующей за командой SAVE. Чтобы воспользоваться новыми возможностями, просто не указывайте первый параметр (локацию) при вызове SAVE. Например:

'''''Пример:'''''
'''save «В лесу»''' ;вызовет интерфейс сохранения с выбором слота
'''save «В лесу», 2''' ;запишет сохранение во второй слот
'''save''' ;просто сохранит игру в нулевой слот без вызова интерфейса

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

==Загрузка игры через оператор LOAD==

Оператор LOAD инициирует загрузку ранее сохранённой игры. Команда дублирует пункт меню «Загрузить сохранение».
Если использовались слоты сохранений, то данная команда вызовет интерфейс выбора из слотов. Если же сохранение было системным, то просто загрузит игру.
== Другое ==

* '''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]]
* Команда '''QUIT''' закрывает плеер с игрой.
* Системная переменная '''fullscreen''' отвечает за развёртывание игры на полный экран и возврат в оконный режим. Установка её в 1 переводит игру в полноэкранный режим, 0 - переводит обратно в оконный.

FireURQ:Руководство пользователя

2014-08-28T09:33:04Z

CHameleon: /* fademusic */

=Текст=
==Вывод текста==

Поскольку мы имеем дело с текстовыми играми, важнейшим для нас является вывод текста. В FURQ существует несколько способов вывода текста.

===Текст на экране===

Простейший способ вывести текст это использовать команды '''P''' и '''PLN'''. Советую освоить их, прежде чем переходить к другим способам вывода.

Формат команд:
'''p''' [текст]
'''pln''' [текст]

Регистр команд не имеет значения ('''pLn''' = '''PLN''' = '''Pln''').

На практике это выглядит так:
'''p''' Этот текст появится на экране.
или
'''pln''' Этот текст тоже появится на экране.

Каждая последующая команда '''P''' или '''PLN''' дописывает новый текст к тексту который уже есть на экране. Когда текста становится слишком много, появляется возможность его прокрутить.

Разница этих двух команд в следующем - '''P''' просто добавляет новый текст, а '''PLN''' добавляет текст и делает переход на новую строку (создает абзац).

Например:
'''p''' А
'''p''' Б

Выдаст “АБ”, тогда как

'''pln''' А
'''pln''' Б

Выдаст:
А
Б

Чаще всего пользуются командой '''pln''', однако и '''p''' может быть полезна, например, когда строчка текста, которую мы хотим вывести на экран, состоит из нескольких частей и зависит от каких-либо переменных или условий.

Команды '''P''' и '''PLN''' могут напрямую выводить любые символы (кроме символа комментария '''“;”'''), переменные и ссылки.

===Вывод переменных===

Вывод переменных возможен в двух вариантах - числовом и текстовом. Для того чтобы их вывести, нужно заключить имена переменных в соответствующие скобки:
'''pln''' '''#%'''имя_текстовой_переменной'''$''' '''#'''имя_числовой_переменной'''$'''
Несмотря на внешнее сходство, они отличаются содержанием и символом '''%'''. Если в числовые скобки попадет текстовая переменная, то на выводе окажется не текст, а количество символов в этой переменной. И наоборот, если числовая переменная попадет в текстовые скобки, то на выводе окажется пустота.

Выведем оба типа переменных на экран:

'''текстовая_переменная="Геннадий"'''
'''числовая_переменная=42'''
'''pln''' Крокодил схватил вас за ногу и сказал:
'''pln''' - Меня зовут '''#%текстовая_переменная$'''.
'''pln''' Затем крокодил схватил вас за другую ногу и сказал:
'''pln''' - Мне '''#числовая_переменная$''' года. Давай, ты станешь моим близким другом.

Результат:
Крокодил схватил вас за ногу и сказал:
- Меня зовут Геннадий.
Затем крокодил схватил вас за другую ногу и сказал:
- Мне 42 года. Давай, ты станешь моим близким другом.

Кроме того, в '''URQL''' есть специальные обозначения для вывода символа пробела - '''#$''', вывода символа переноса строки - '''#/$''' и вывода символа по ascii-коду - '''##'''ascii-код'''$'''.

Так, например, символ комментария можно вывести на экран, через его ascii-код:
'''pln''' Моя грамотность была на исходе'''##59$''' но, несмотря на это, я поставил точку с запятой в предложении.

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

Хочу напомнить, что если бы мы написали в коде просто:
'''pln''' Моя грамотность была на исходе; но, несмотря на это, я поставил точку с запятой в предложении.
То получили бы на экране:
Моя грамотность была на исходе
Потому что символ ";" и все что после него идет было бы обработано как комментарий.

==Оформление текста==

В 21 веке в '''FURQ''' текст это не просто набор символов, но еще и набор гарнитур, цвет, выравнивание и местоположение.

===Местоположение===
Область экрана, куда выводят текст команды '''p''' и '''pln''' можно двигать, делать шире, уже, выше и т.д. Для этого служат системные переменные '''textpane_left''', '''textpane_top''', '''textpane_width''' и '''textpane_height''', которые описывают некий прямоугольник куда и выводится текст. По умолчанию он занимает почти весь экран. Это числовые переменные, которые содержат значения в пикселях.

Давайте, используя полученные нами знания, выведем значения этих переменных на экран:
'''pln''' Левая граница='''#textpane_left$''', Верхняя граница='''#textpane_top$''', Ширина='''#textpane_width$''', Высота='''#textpane_height$'''

Результат:
Левая граница=20, Верхняя граница=55, Ширина=760, Высота=525

Вы можете изменять значения этих переменных как угодно в любом месте игры. Например, вы хотите вывести справа от текста картинку: измените ширину ('''textpane_width''') так чтобы текст не мешал. А когда картинка больше не нужна измените ширину обратно. Экспериментируйте.

===Выравнивание текста===

За выравнивание текста отвечает команда числовая системная переменная textalign. Она сообщает FURQ как должен быть расположен текст относительно области его вывода.

Лучше всего это понять на примере:
'''textalign = 1'''
'''pln''' текст выравнивается влево
'''textalign = 2'''
'''pln''' текст выравнивается вправо
'''textalign = 3'''
'''pln''' текст выравнивается по центру

''; Главное теперь не забыть, поменять переменную обратно на '''1''', если вы не хотите, чтобы текст всей игры был выравнен по центру.''

===Цвет===

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

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

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

===Шрифт===

Для определения шрифта, которым будет выводиться текст, используется переменная '''textfont'''. В нее в виде строкового значения следует записать имя файла шрифта.

'''FireURQ''' позволяет использовать обычные True Type шрифты Windows. Для этого шрифт должен быть либо установлен в системе, либо лежать в папке с игрой (архиве QSZ).

Формат использования шрифта такой:
'''textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]'''

*'''size''' – размер шрифта(по умолчанию '''19'''), а точнее высота строки в пикселях
*'''gamma''' – гамма, т.е. "светлость" границ шрифта(по умолчанию '''1.0''')
*'''weight''' – толщина(по умолчанию '''0.6''')
*'''bgcolor''' – цвет подложки (по умолчанию '''0x808080''')

Допустим, мы хотим вывести текст шрифтом Georgia.

Для этого пишем:
'''textfont = "georgia.ttf"'''
И сразу же проверяем результат, при помощи оператора вывода текста '''pln''', который мы уже освоили в совершенстве:
'''pln Крокодил зарылся в ил, крокодила ил манил'''

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

Меняем размер на 42:
'''textfont = "georgia.ttf[42]"'''

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

Примеры:
'''textfont = "georgia.ttf[20,1.1]"'''
'''textfont = "verdana.ttf[10,,,0xFFFFFF]"'''
'''textfont = "timesi.ttf[32,,1.3]"'''

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

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

Пример использования HGE шрифта
'''textfont = "myfont.fnt"'''

===Команда CLS===

Часто бывает так, что экран, на который уже выведен текст нужно очистить. Для того чтобы удалить весь текст, выведенный при помощи команд '''P''' и '''PLN''', существует команда '''CLS'''. У нее нет никаких параметров.

Пример:
'''pln Уйма текста.'''
'''cls'''

Результат:
 

===Другие способы вывода текста===

Иногда оказывается недостаточно команд, описанных выше. Например, вы хотите чтобы в верхнем правом углу экрана всегда отображалось количество очков, которые игрок заработал на протяжении игры. Или состояние здоровья персонажа. Или название комнаты, в которой он находится. Или все это одновременно в разных местах экрана. Тогда на помощь автору приходят текстовые [[декораторы]].

===Текст в заголовке===

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

Пример:
'''gametitle = “Крокодил”'''

Результат:

[[Изображение:Furq_titlebar.png]]

''; Иногда эту переменную удобно использовать при отладке игры, временно выводя в нее, к примеру, значения других переменных.''

= Музыка и звук =

В '''FURQ''' есть целый ряд команд для воспроизведения аудио. Оно может быть всевозможных форматов: WAV, AIFF, MP3, MP2, MP1, OGG, MIDXM, IT, S3M, MOD, MTM, UMX. Есть возможность тонкого регулирования громкости звука.

Для начала запасемся на ресурсах, где свободно распространяют звуки (например, www.freesound.org) или запишем сами материала для проигрывания.

==Play==

Команда '''Play''' используется для проигрывания аудиофайлов формата WAV/AIFF/MP3/MP2/MP1/OGG

Формат команды:
'''play [loop|stop] [<имя файла>[, <громкость>]]'''

Чтобы просто запустить звук на проигрывание с помощью play напишите после команды имя файла. Например, нужно проиграть некий звук крокодила ''alligator.ogg''. Для этого пишем:
'''play alligator.ogg'''

Если файл alligator.ogg лежит рядом с файлом игры, то мы услышим нечто. Но если мы для удобства положим все звуки в отдельную папку sounds, то придется написать так:
'''play sounds/alligator.ogg'''

В нашем примере звук крокодила будет звучать всего один раз, однако, при помощи параметра '''loop''' мы сможем заставить крокодила двигаться и звучать бесконечно:
'''play loop sounds/alligator.ogg'''

Теперь звук будет повторяться снова и снова. Остановить его сможет только параметр '''stop''':
'''play stop sounds/alligator.ogg'''

При помощи '''Play''' можно одновременно проигрывать несколько звуков. Кроме того, можно регулировать громкость звука, добавив к команде play через запятую значение от '''0''' (полная тишина) до '''255''' (максимальная громкость). По умолчанию, '''play''' играет аудио с максимальной громкостью.

К примеру, мы хотим, одновременно наслаждаться звуком крокодила и чмоканием болота, но так, чтобы крокодил был слышен громче:
'''play loop sounds/alligator.ogg'''
'''play loop sounds/swamp.wav, 100'''

Чтобы остановить сразу все звуки, запущенные командой '''play''', мы применим такую на первый взгляд абсурдную команду как:
'''play stop'''

''; Важно помнить, что звуки запущенные на одной локации через '''play''' с параметром '''loop''' без новой команды с параметром '''stop''' сами собой не прекратятся, даже если вы перешли на другую локацию. И если вы вдруг оттуда вернетесь на прежнюю локацию, то те же самые звуки запустятся еще раз. Добро пожаловать в какафонию.''

==Voice==

Команда '''Voice''' используется для проигрывания аудиофайлов формата WAV/AIFF/MP3/MP2/MP1/OGG

Формат команды:
'''voice <имя файла>'''
'''voice stop'''

Команда предназначена специально для озвучивания игры голосом. Например, ей удобно запускать записи реплик персонажей или рассказчика. Во многом она аналогична команде '''play''', но с несколькими важными особенностями:
Проигрывать можно только одну реплику/звук одновременно(запуск другой озвучки через команду voice останавливает предыдущую).

Переход на другую локацию по кнопке ('''btn''') останавливает озвучку.

Громкость здесь регулируется числовой переменной '''voice_volume''' (от '''0''' до '''255''').

Остановить проигрывание файла можно при помощи команды '''voice stop'''.

Если вам необходимо чтобы прозвучало несколько реплик на одной локации, то достаточно удобно использовать команду voice в связке с командой '''anykey'''. Прослушав реплику, игрок будет нажимать на любую клавишу и слушать следующую.

Например:

'''voice_volume=200'''
'''pln - Еще раз здравствуй. - сказал крокодил и придвинулся поближе.'''
'''voice sounds/helloagain.ogg'''
'''anykey'''
'''pln Вам стало не по себе.'''
'''voice sounds/SCREAM.wav'''

==Music==

Кроме форматов аудиофайлов, которые воспроизводят команды '''play''' и '''voice''', команда '''music''' проигрывает еще и трекерную музыку (XM, IT, S3M, MOD, MTM, UMX), MIDI-файлы (MID) и MO3.

Формат команды:
'''music <имя файла>|stop[, <время в миллисекундах>]'''

Зацикливание проигрывания устанавливается в переменной music_looped ('''0''' - играть один раз, '''1''' - играть бесконечно). По умолчанию, вот отличие от команд '''play''' и '''voice''', здесь музыка зациклена.

''; некоторые файлы трекерной музыки зациклены сами по себе, с помощью внутренних команд формата. Такие файлы будут играть по кругу вне зависимости от переменной '''music_looped'''.

''Громкость воспроизведения регулируется переменной music_volume (от '''0''' до '''255''').

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

Так “'''music stop'''” останавливает воспроизведение музыки. А если указать в качестве параметра время, то воспроизведение остановится через заданный промежуток.
'''music stop, 1500 ''; остановить музыку через 1,5 секунды'''''

===fademusic===

С помощью команды '''fademusic''' можно добиться плавного и красивого изменения громкости музыки.
Формат команды:
'''fademusic <громкость>, <время в миллисекундах>'''
громкость – целевая громкость музыки.

время в миллисекундах – время, в течении которого громкость достигнет целевого значения.

Предположим, что мы хотим сделать красивое и удобное включение и выключение музыки в нашей игре. Для этого используем [[инвентарь]] '''URQ'''. Игрок в любой момент сможет через пункт меню инвентаря включить и выключить музыку, а мы постараемся, чтобы это было плавно. На самом деле выключать музыку совсем мы не будем, а будем только понижать громкость до нуля, но зато нам не придется задаваться вопросом какой именно файл запускать при включении музыки.

В начале игры создадим элемент инвентаря “музыка” и присвоим ему наклейку “выключить музыку”:
'''inv+ музыка'''
'''idisp_музыка = "выключить музыку"'''
Запускаем любую музыку, в любом месте игры:
'''music music\Joe Hisaishi - Пылью на твоих руках.mp3'''
Теперь, в локации, которая отвечает за наш элемент инвентаря “музыка” используем оператор '''fademusic''':
''':Use_музыка'''
'''if idisp_музыка == "включить музыку" then idisp_музыка = "выключить музыку" & fademusic 255, 1500 else idisp_музыка = "включить музыку" & fademusic 0, 1500'''
'''end'''
Теперь по нажатию на “выключить музыку” громкость будет плавно затихать до нуля за 1,5 секунды, а по нажатию на “включить музыку” - так же плавно возрастать.

[[Категория:Документация FireURQ]]