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

Метки

Метка - одно из важнейших понятий URQL. Она служит для выделения места в квесте, куда затем предстоит перейти. Любые перемещения в квесте могут быть либо на следующий оператор, либо на метку. Все метки имеют имена, чтобы потом можно было указывать, куда вы хотите перейти. Определяется метка при помощи двоеточия. Все, что правее этого символа, до разделителя, которым является символ конец абзаца (Enter) или '&' - имя метки:

:Имя_метки

Метка и следующий за ней оператор end являются принятой единицей измерения игры - локацией. Между ними обычно пишется описание локации и переходы из неё в другие локации.

:начало
end

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

:1
:01
:а
:кот1
:@(a)%^Очень_Длинная_и_Запутанная_метка_какими-лучше-не-пользоваться!!!!!_horror_так_как_сами_потом_забудете_как_она_называется!Или_сделаете_ошибку!
Вы_же_можете_сделать_маленькую_ошибку_в таком_длинном_названии?
:house_flat1

Примечание: метка должна начинаться с начала строки и отделяться от других операторов (Enter) или '&', регистр имени метки не важен.

:BIG
:bIG
:Big
:big
- все эти метки для интерпретатора совершенно одинаковы. Но лучше, в целях собственного удобства, придерживаться единого стиля.

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

Недопустимы символы ; /* */ &

Грамотное использование имен меток способно серьезно облегчить работу автора.

Текст

Вывод текста

Поскольку мы имеем дело с текстовыми играми, важнейшим для нас является вывод текста. В 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 = “Крокодил”

Результат:

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

Переходы

Любой текстовый квест можно разбить на локации с текстом и переходы между ними. Из каждой локации к другим локациям обычно ведет несколько переходов, которые обозначают некоторые альтернативные варианты действий. В этой главе мы рассмотрим способы, которыми URQL позволяет сделать переходы в игре.

Переход по кнопкам (оператор BTN)

Самый распространённый переход осуществляется с помощью кнопок. Кнопки всегда расположены после выведенного текста и используются для переходов по меткам. Примечание: лучше ставить между текстом и кнопками лишний оператор pln - так ваша игра будет выглядеть гораздо лучше.

Общее обозначение: btn <локация>, <надпись на кнопке>]

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

Пример:

btn лес,Войти в лес
Эта команда выведет на экран кнопку с текстом Войти в лес, ведующую на локацию лес

Примечание 1: пробелы до и после надписи на кнопке игнорируются.

Примечание 2: если локация не найдена, то кнопка выводится с пометкой // phantom.

Примечание 3: при наличии локации common (см. ниже) сначала выполняются операторы на локации common, потом осуществляется переход на метку локации.

У кропок есть так называемое "эхо". Это сообщение, выводящееся на экран о том, что вы перешли по кнопке. Чтобы оно не выводилось, следует использовать переменную hide_btn_echo. Если установить её в единицу, то сообщения показываться не будут.

Пример:

hide_btn_echo = 1

Команда CLSB

Бывает так, что нам не нужно очищать весь экран, а нужно стереть только кнопки действий. Для того чтобы удалить кнопки выведенные командой BTN, существует команда CLSB. У нее нет никаких параметров.

Пример:

btn север, Идти на Север
clsb
btn юг, Идти на Юг

Результат (текст на выведенной кнопке):

Идти на Юг
   

Оформление кнопок в Fireurq

Оформление кнопок делается в файле skin.xml Описание можно найти в статье FireURQ:Скины.

Переход по ссылке

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

Формат ссылок:

[[текст ссылки|название локации]]

Пример:

pln Вы стоите рядом с покосившимся [[домиком|домик_осмотреть]]. Вокруг раскинулись [[клумбы с аромантными цветами|клумбы_осмотреть]].

Здесь домик_осмотреть и клумбы_осмотреть - названия локаций, на которые будут осуществляться переходы при нажатии на ссылку.

Цвет ссылок задаётся переменными linkcolor и linkhcolor. Первая отвечает за цвет ссылки в тексте, а вторая - за цвет ссылки при наведении мыши.

Пример:

linkcolor = 0xffffff
linkhcolor = 0x0000ff
В данном примере цвет ссылок в тексте будет белым, а при наведении станет синим.

Невалидные ссылки (указывающие на несуществующую локацию) всегда подсвечены красным цветом.

Упрощенный формат вывода ссылок такой:

[[текст ссылки]]

В данном случае ссылка будет вести на метку под названием "текст ссылки".

Пример:

pln На волнах раскачивается деревянная [[лодка]].

Здесь, при клике на ссылку произойдет переход на метку "лодка".

Замечание: не рекомендуется называть метки именами с пробелами, соответственно не стоит использовать ссылки типа [[деревянная лодка]], которые ведут на локации с такими именами.

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

Пример:

hide_link_echo = 1

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

Локальные параметры при переходах возможно передать параметры.

Общее обозначение: <метка>(param1, param2, ...)

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

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

Пример:

btn лес(1,"опушка"),Войти в лес
На локации лес, переменные лес_1 и лес_2 будут соответссвенно равны 1 и опушка

то есть, если мы напишем код:
:лес
pln #лес_1$ и #%лес_2$
end
то в результате, при переходе по кнопке, увидим на экране:
1 и опушка

Параметры при переходах очень удобны для организации проверок внутри локации.

Замечание: Если вы передаёте параметры метке, то её название не должно начинаться с цифры, то есть исключены названия вроде 25 или 40метро. Если вы хотите использовать цифры в названии, то ставьте их после букв, к примеру - метро40.

Музыка и звук

В 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 секунды, а по нажатию на “включить музыку” - так же плавно возрастать.