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

Операции

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

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

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

Подстановка #...$ работает для числовых значений переменных, тогда как #%...$ для текстовых. Для подробностей см. руководство.

Параметры при переходах

При переходах (операторы proc, btn и goto) возможно передать параметры на метку, на которую происходит переход. Синтаксис:

goto <метка>[(param1, param2, ...)]
proc <метка>[(param1, param2, ...)]
btn <метка>[(param1, param2, ...)], <текст на кнопке>

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

Важное замечание: при использовании параметров в операторе btn подстановки (#...$ и #%...$) раскрываются ПРИ ДОБАВЛЕНИИ КНОПКИ, а вычисление выражений в параметрах производится ПРИ НАЖАТИИ НА КНОПКУ.

Пример:

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 some.ogg, -1500

Переменная is_music равна 1, если в игре играет музыка, и 0 — если нет.

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

Возможно плавное изменение громкости музыки командой fademusic:

fademusic <громкость>, <время в миллисекундах>

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

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

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

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

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".

Важное замечание: вполне возможно писать разными шрифтами внутри одного абзаца текста. Но этого не рекомендуется делать со шрифтами разных размеров. Формат HGE Font не предусматривает такое понятие, как «базовая линия». Поэтому, куски текста, написанные разными шрифтами, будут «прыгать» относительно друг друга.

TrueType шрифты используются так:

textfont = "file.ttf[<size>, <gamma>, <weight>, <bgcolor>]"

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

Параметры можно опускать.

Важное замечание: Поскольку из TTF генерится битмапный шрифт и края должны "подходить" к фону, на котором потом выводится текст, то для идеального отображения шрифта можно подставить соответствующий цвет в bgcolor. Gamma и weight по умолчанию подобраны для шрифтов на чёрном фоне. Возможно, для светлого фона их нужно немного поменять.

Примеры:

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 позволяет использовать в тексте кнопки. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам. Начиная с версии 1.9.1, формат кнопок таков:

btn <локация>[(param1, param2, ...)][, <надпись на кнопке>]

Где <локация> - имя метки, на которую будет совершен переход, param1, param1 и т.д. - параметры, передаваемые в эту локацию, <надпись на кнопке> - надпись на кнопке, которая отображается на экране. В случае если <надпись на кнопке> не указана, в качестве надписи используется название метки, куда ведет кнопка.

Пример:

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

Ссылки

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

С версии 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.png,
определив начальную картинку из текстуры с позиции 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-файла" 

Важное замечание: В декораторах типа IMAGE можно использовать gif-изображения, но они будут статичными (первый кадр в анимированных gif-ах). Для анимированных gif-ов используйте декоратор с типом GIF.

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

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 при проигрывании вашего квеста. Изменение внешнего вида интерпретатора - это тема повышенной сложности, поэтом она раскрыта в отдельном разделе.

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

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

Также, в старых версиях FireURQ (до версии 2.0) существовала возможность конвертации квеста в формате QSZ в исполняемый файл с помощью утилиты QSZ2EXE, входившей в комплект поставки.

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

Режим отладки включается с помощью ключа -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 ;просто сохранит игру в нулевой слот без вызова интерфейса

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

При сохранении игры командой SAVE переменная save_success устанавливается в 1 при успешном сохранении и в 0, если сохранение по каким-то причинам не удалось.

Так же с версии 2.2 в FireURQ появилась возможность менять базовое имя файла сейва. Переменная savenamebase хранит это имя. По умолчанию переменная содержит название файла игры. Если значение поменять на «profile1», то файлы сохранений будут называться profile1.s01, profile1.s02 и т.д.

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

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

C версии FireURQ 2.2 появилась возможность загружать сохранения непосредственно из слотов, не вызывая меню "Загрузить сохранение".

Если написать LOAD 1, то будет загружено сохранение из первого слота. LOAD 0 загрузит игру из слота автосохранения.

Перманентное хранилище данных

Начиная с версии 2.2 FireURQ обзавелась перманентным хранилищем данных. Это переменные, которые не удаляются при perkill или перезапуске игры, автоматически подгружаются и, при их изменении, так же автоматически сохраняются в специальном файле.

Любая переменная, начинающаяся на gss_ будет считаться перманентной.

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

Команда gsskill полностью очищает хранилище.

Другое

• 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.
• Команда QUIT закрывает плеер с игрой.
• Системная переменная fullscreen отвечает за развёртывание игры на полный экран и возврат в оконный режим. Установка её в 1 переводит игру в полноэкранный режим, 0 - переводит обратно в оконный.
• Переменная altenter_disable (по умолчанию 0) отвечает за то, что по комбинации клавиш Alt + Enter окно игры будет открываться на весь экран или становиться снова окном. Для отключения реакции на эту комбинацию клавиш, следует установить переменную в 1.
• Переменная escape_disable (по умолчанию 0) отвечает за показ системного меню по нажатию клавиши Esc. Для отключения реакции на эту клавишу, следует установить переменную в 1.