Функции
$CURACTS
$CURACTS
— данная функция возвращает выведенные на экран действия в виде кода QSP, как текстовое значение.
Действия сохраняются в виде набора операторов act
с cответствующими параметрами и операциями.
Записав возвращённое функцией значение в переменную, можно восстановить действия с помощью оператора dynamic
. Пример:
! записываем текущие действия в переменную
$actlist = $curacts
! восстанавливаем действия из переменной
dynamic $actlist
$CURLOC
$CURLOC
— функция возвращает название текущей локации, т.е. локации, в которой "находится" игрок.
Технически это следует понимать так. В момент запуска игры плеер начинает выполнять код самой первой локации в игре, а когда код выполнен, плеер "останавливается" и ждёт участия игрока. Игрок может нажимать различные кнопки в игре, ссылки и выбирать пункты меню, что приводит к выполнению других блоков кода (например, действий) и переходам на новые локации по goto
или xgoto
. При таких переходах плеер вновь выполняет код других локаций и, когда код выполнен, "останавливается".
Так вот, когда на локацию осуществлён непосредственный переход (т.е. по goto
или xgoto
, либо это самая первая локация в игре), $curloc
начинает возвращать название этой локации, — во всё время, пока выполняется код, и когда плеер "останавливается". Если после остановки не происходит переход по goto
/xgoto
, значение, которое возвращает $curloc
, не меняется.
Пример использования:
*pl $curloc & ! выводим название текущей локации в Окно основного описания
*pl "Сколько раз перезашли: <<перезашёл>>"
act "Перезайти на текущую локацию":
перезашёл += 1
goto $curloc
end
$DESC
$DESC
— возвращает текст базового описания локации с заданным названием. Общая запись:
$DESC([$локация])
, где [$локация]
— это название интересующей нас локации. Например:
! возвращаем базовое описание локации "каморка_под_лестницей"
$desc('каморка_под_лестницей')
!возвращаем базовое описание текущей локации
$desc($curloc)
Если в базовом описании присутствуют подвыражения, функция автоматически раскрывает их.
Функция возвращает текст, написанный только в поле "Описание" (Базовое описание) редактора Quest Generator. При работе в текстовом редакторе данное поле вам недоступно и функция будет всегда возвращать пустую строку.
$DYNEVAL
DYNEVAL
— выполняет код, переданный в виде строки текста, и возвращает результат, если он есть. Общая запись:
$DYNEVAL([$код], [аргумент 0], [аргумент 1], ... , [аргумент 18])
DYNEVAL([$код], [аргумент 0], [аргумент 1], ... , [аргумент 18])
, где [$код]
— это обычный код QSP, записанный в виде текста. Выполнение такого кода аналогично выполнению кода функции FUNC
. Аргументы [аргумент 0]
, [аргумент 1]
и т.д. могут использоваться внутри [$код]
, их значения автоматически помещаются в переменные args[0]
, args[1]
, и т.д. соответственно.
Внутри выполняемого кода dyneval
используется свой собственный массив ARGS
, его значения не пересекаются со значениями ARGS
на локации, из которой dyneval
была вызвана.
После выполнения кода, переданного функции dyneval
, продолжается вычисление выражения, в котором расположена функция dyneval
.
Чтобы dyneval
возвращала результат, необходимо внутри [$код]
присвоить этот результат переменной result
.
Примеры:
dyneval('result = 3 + 4')
*pl $dyneval('$result = mid("abcd", 2, 1) + "qwerty"')
проход = dyneval("result = ($args[0] <> 'текст')", 'строка')
- Чтобы
DYNEVAL
вернула строковое значение, результат должен быть записан в$RESULT
. - Чтобы
DYNEVAL
вернула числовое значение, результат должен быть записан вRESULT
. $RESULT
иRESULT
— это одна и та же переменная, но с разными типами данных. Следует помнить, что новая запись значения затирает предыдущее, какого бы типа данных не было это значение.
Если при выполнении dyneval
она не возвращает значения (result
не инициализируется), и является единственным элементом выражения, передаваемого неявному оператору, плеер ничего не выведет на экран. Т.е. dyneval
будет работать, как DYNAMIC
. Пример:
! неявный оператор выведет на экран 123:
123
! код в dyneval выполнится, но на экране
! мы ничего не увидим:
dyneval("code = 123 + 890")
! неявный оператор выведет на экран 1013:
code
См. также оператор DYNAMIC
.
$FUNC
FUNC
— выполнение кода указанной локации без непосредственного перехода на неё с возвращением значения.
Общая запись:
FUNC([$локация], [аргумент 0], [аргумент 1], ... , [аргумент 18])
$FUNC([$локация], [аргумент 0], [аргумент 1], ... , [аргумент 18])
, где [$локация]
— это название локации, код которой мы хотим выполнить без непосредственного перехода на неё. Аргументы [аргумент 0]
, [аргумент 1]
и т.д. могут использоваться на этой локации, их значения автоматически помещаются в переменные args[0]
, args[1]
, и т.д. соответственно.
Чтобы FUNC
вернула строковый результат, на указанной локации нужно присвоить этот результат переменной $RESULT
. Для возвращения числового результата, он должен быть присвоен переменной RESULT
. Следует помнить, что $RESULT
и RESULT
— это одна и та же переменная, но разных типов, поэтому если вы определили на локации и $RESULT
и RESULT
, функция вернёт то значение, которое было записано в эту переменную последним.
Если переменной RESULT
не было присвоено ни строковое, ни числовое значение, функция ничего не вернёт. И тут есть два варианта поведения плеера.
-
Если функция
FUNC
стоит в каком либо выражении, вместо функции будет подставлено значение по умолчанию (пустая строка или ноль в зависимости от типа самого выражения). -
Если функция
FUNC
стоит сразу после неявного оператора, такой оператор будет проигнорирован, и на экран ничего выводиться не будет. Пример:локация_НN = 23 * 13
! ни одно значение не присваивается переменной resultДругая локация'строка 1'
func('локация_Н') &! ничего не выведется на экран
'строка 2'
56 + func('локация_Н') &! функция стоит в выражении. Её значение = 0
Не обязательно, но рекомендуется, записывать ключевое слово FUNC
с символом $
, если функция должна вернуть текстовое значение, и без символа $
, если функция должна вернуть числовое значение:
$func('срез_строки', 'Мы вышли из дома, когда во всех окнах погасли огни.', 3, 7)
func('возвести_в_степень', 3, 3)
При вызове указанной локации с помощью FUNC
происходит следующее:
- Плеер прерывает выполнение текущего кода (например, кода текущей локации), и обращается к указанной локации.
- Базовое описание и список действий указанной локации добавляются к описанию и действиям текущей локации.
- Выполненяется код из поля Выполнить при посещении
- Затем плеер возвращается к выполнению кода, который прервал. То есть к вычислению выражения, в котором стоит данная функция.
На каждой локации автоматически создаются свои собственные уникальные массивы ARGS
и RESULT
, поэтому значения в этих массивах для каждой локации будут свои собственные. После выполнения кода локации, вызванной по FUNC
, массивы ARGS
и RESULT
этой локации уничтожаются.
Другие примеры:
!Обработка локации "функция" как функции.
!Массив ARGS пуст.
яблоки = FUNC('функция')
!обработка локации с названием лежащим в переменной $name как функции. ARGS[0] равен 1.
pl func($name, 1) * 78
!обработка локации с названием в $name как функции.
!$ARGS[0] содержит строку "строка", ARGS[1] равен 2.
msg "text" + func($name, "строка", 2)
! код локации для функции, получающей сумму ряда чисел от единицы до указанного значения
# summ
! в args[0] будет помещено число, которое мы укажем в качестве [аргумента 0]
loop while args[0]>0 step args[0] -= 1:
result += args[0]
end
---summ---
! пример вызова локации "summ", как функции
*pl func("summ", 19) & ! выведет на экран 190
! пример вызова с записью названия локации в переменную
$name_loc = "summ"
*pl func($name_loc, 23) & ! выведет на экран 276
$GETOBJ
$GETOBJ
— возвращает название предмета в Окне предметов, расположенного в заданной позиции. Общая запись:
$GETOBJ([#номер предмета])
Индексация (нумерация) предметов в Окне предметов ведётся с 1. Если предмета с индексом [#номер предмета]
не существует, возвращается пустая строка (''
).
Примеры:
$getobj(1) & ! вернёт название первого предмета в рюкзаке
$getobj(countobj) & ! вернёт название последнего добавленного предмета
Код, подсчитывающий в массиве OBJECTS
число предметов с одинаковым названием:
loop local i = 1 while i <= countobj step i += 1:
objects[$getobj(i)] += 1
end
$IIF
IIF
— возвращает значение в зависимости от верности выражения.
Общая запись:
IIF([#выражение], [#выражение_да], [#выражение_нет])
$IIF([#выражение], [$выражение_да], [$выражение_нет])
Если [#выражение]
верно, возвращает значение выражения [выражение_да]
, в противном случае возвращает значение выражения [выражение_нет]
.
Из выражений [выраажение_да]
и [выражение_нет]
будет вычислено только одно, в зависимости от того, будет ли выполнено условие.
Примеры:
!Модуль числа
abs_x = iif(x>0, x, -x)
!А следующая конструкция НЕ вызовет ошибку деления на ноль:
x = 0
y = iif(x = 0, 0, 1/x)
! типичное решение для вывода времени, чтобы не терять ноль на часах:
$iif(hour>9, $str(hour), "0"+$str(hour)) + ":"+$iif(minute>9, $str(minute), "0"+$str(minute))
Эквивалентность конструкций условия с оператором IF
и функции IIF
:
if number mod 2 = 0:
*pl "Число чётное"
else
*pl "Число нечётное"
end
! эквивалентно
*pl $iif(number mod 2 = 0,"Число чётное","Число не чётное")
$INPUT
$INPUT
— возвращает интерпретатору введённый игроком текст, либо ''
(пустая строка), если была нажата кнопка "Отмена". Общая запись:
$INPUT([$текст])
, где [$текст]
— это приглашение в диалоговом окне, которое видит игрок. Например:
$name = $input('Как звать тебя, герой?')
При выполнении данной команды на экране появится ди алоговое окно с текстом "Как звать тебя, герой?", а выполнение остального кода приостановится, пока игрок не провзаимодействует с диалоговым окном.
Игрок может ввести или не ввести текст, и нажать кнопку "ОК" или "Отмена". Если игрок ввёл текст и нажал кнопку "ОК", функция $input
вернёт переменной $text
введённый игроком текст. Во всех остальных случаях после закрытия диалогового окна функция вернёт пустую строку (''
).
Другие примеры:
! Вопрос с одним правильным ответом.
if $input('Что приходит после тьмы?') = 'свет':
msg 'Все верно.'
else
msg 'Ответ не верный.'
end
! Пример реализации вопроса с несколькими вариантами ответа из которых любой будет правильным.
$answer = $trim($lcase($input('Ответить')))
if instr($answer, 'красный') or instr($answer, 'желтый') or instr($answer, 'зеленый'): gt 'win'
! Введя красный или зеленый ил желтый произойдет переход на локацию 'win'
Допустимо, но не одобряется, использовать функцию для возвращения числовых значений:
INPUT([$приглашение])
Это может привести к различным ошибкам в игре, если игрок введёт в диалоговом окне не только цифры. Например:
age = input('Сколько вам лет?')
Если игрок введёт вместо числа строку "24 года", плеер выдаст ошибку 101 "Несоответствие типов данных". Подобные ситуации должен предусматривать автор игры, а значит правильно будет озаботиться проверкой введённого значения уже после того, как функция $input
будет выполнена.
loop local $text while 1:
! предлагаем игроку ответить на вопрос
! и присваиваем введённый текст переменной
$text = $input('Сколько вам лет?')
! если во введённом тексте содержатся не только цифры
! либо игрок не ввёл ответ
if isnum($text) and $text <> "":
! игрок ввёл число
age = val($text) & ! устанавливаем возраст
jump 'break' & ! прерываем цикл
else
! игрок ничего не ввёл или ввёл некорректно е значение
! цикл продолжается
end
end
:break
$LCASE
$LCASE
— возвращает строку маленьких букв, полученную изменением регистра букв исходной строки. Общая запись:
$LCASE([$текст])
, где [$текст]
— любая строка текста.
Примеры:
$lcase('TExT#') & ! вернёт 'text#'
$lcase('Привет, Алиса!') & ! вернёт 'привет, алиса!'
$lcase('Я НЕ ХОЧУ НА ВАС ОРАТЬ.') & ! вернёт 'я не хочу на вас орать.'
$MAINTXT
$MAINTXT
— возвращает текст, выведенный в окно основного описания.
Данная функция может быть полезна для замены части текста в окне основного описания, либо иной обработке текста. Пример:
! изначально мы вывели строку
*pl "Мы вывели на экран строку и в этой строке есть кусок, который мы хотим удалить."
! получаем текст из окна основного описания
$text = $maintxt
! вырезаем лишний кусок
$text_new = $replace($text, " и в этой строке есть кусок, который мы хотим удалить")
! очищаем окно основного описания
*clr
! выводим новый текст
*p $text_new
$MAX
MAX
— возвращает максимальное из значений выражений-аргументов. Можно передавать от одного до двадцати значений/аргументов. Если передан один аргумент, то считается, что указано имя массива. Общая запись:
MAX([#выражение 1], [#выражение 2], ... , [#выражение 20])
$MAX([$выражение 1], [$выражение 2], ... , [$выражение 20])
MAX([$название массива])
$MAX([$название массива])
Обратите внимание, при передаче одного аргумента поиск максимального элемента происходит среди строковых (если название массива указано со знаком $
) или среди числовых значений элементов массива. Например:
max('a') & ! вернёт максимальное из числовых значений элементов массива "a"
$max('$b') & ! вернёт максимальное из строковых значений элементов массива "b"
Нельзя писать так и надеяться, что произойдёт поиск среди значений массива a
:
max(a)
Можно так:
$b = 'a'
max($b) & ! произойдёт поиск максимального значения среди элементов массива "a"
Другие примеры:
max(1, 2, 5, 2, 0) &! вернёт 5
max(a, b, c) &! вернёт максимальное из значений переменных a,b,c
$max('aa', 'ab', 'zz') &! вернёт 'zz'
$MID
$MID
— позволяет вырезать из строки её часть. Общая запись:
$MID([$строка], [#начало], [#длина])
, где [$строка]
— это строка текста, именно из неё функция вырезает часть, начиная с символа номер [#начало]
, и длиной в [#длина]
символов. Нумерация символов начинается с 1.
- Если отсутствует параметр
[#длина]
, вырезается часть до конца строки. - Параметр
[#начало]
обязателен, и может в принципе принимать любые значения. - Если значение
[#начало]
превышает длину строки, возвращается пустая строка.
$mid('abcdef', 1, 2) & ! 'ab'
$mid('abcdef', 2, 3) & ! 'bcd'
$mid('abcdef', 2) & ! 'bcdef'
$mid('abcdef') & ! 'ошибка [120] — неверное число аргументов оператора/функции'
$mid('abcdef', 0) & ! 'abcdef'
$mid('abcdef', 8) & ! ''
$MIN
MIN
— возвращает минимальное из значений выражений-аргументов. Можно передавать от одного до двадцати значений/аргументов. Если передан один аргумент, то считается, что указано имя массива. Общая запись:
MIN([#выражение 1], [#выражение 2], ... , [#выражение 20])
$MIN([$выражение 1], [$выражение 2], ... , [$выражение 20])
MIN([$название массива])
$MIN([$название массива])
Обратите внимание, при передаче одного аргумента поиск минимального элемента происходит среди строковых (если название массива указано со знаком $
) или среди числовых значений элементов массива. Например:
min('a') & ! вернёт минимальное из числовых значений элементов массива "a"
$min('$b') & ! вернёт минимальное из строковых значений элементов массива "b"
Нельзя писать так:
min(a)
Можно так:
$b = 'a'
min($b) & ! произойдёт поиск максимального значения среди элементов массива "a"
Другие примеры:
min(1, 2, 5, 2, 0) & ! вернёт 0
min(a, b, c) & ! вернёт минимальное из значений переменных a,b,c
$min('aa', 'ab', 'zz') & ! вернёт 'aa'
$QSPVER
$QSPVER
- возвращает версию интерпретатора в формате "X.Y.Z Player". Например, классический плеер версии 5.8.0. возвращает значение "5.8.0 (classic)", а qSpider просто "5.8.0". Пример использования:
if $qspver < "5.8.0":
*pl "Ваша версия плеера не подходит для этой игры."
*pl "Установите плеер версии 5.8.0 или выше."
end
Так же данная функция может возвращать платформу, на которой запущена игра, если указать аргументом значение "platform":
$qspver('platform')
$REPLACE
$REPLACE
— общая запись:
$REPLACE([$строка], [$поиск], [$замена])
Данная функция заменяет в строке [$строка]
все вхождения строки [$поиск]
строкой [$замена]
и возвращает результат. Если [$замена]
отсутствует или указана пустая строка, то удаляет в исходной строке все вхождения искомой строки. Примеры:
$replace('test', '12', '4') & ! выведет на экран 'test'
$replace('test', 'e', 's') & ! выведет на экран 'tsst'
$replace('test', 't', '34') & ! выведет на экран '34es34'
$replace('test', 't') & ! выведет на экран 'es'
! можно присвоить значение переменной
$text = "Строка текста с разными буквами."
! а новое значение вписать в другую переменную
$text_new = $replace($text, "ст", "st")
*pl $text
*pl $text_new
$SELACT
$SELACT
— возвращает название выделенного действия в любом месте игры.
Следует помнить, что выделение действия происходит при наведении на него указателя мыши, а не при непосредственном нажатии.
Наиболее часто эту функцию используют, чтобы удалить текущее действие:
act "Съесть яблоко":
*pl "Это было очень вкусное яблоко. Жаль, что червивое."
здоровье += 100
delact $selact
end
Так же смотрите примеры использования в разделе $onactsel
$SELOBJ
$SELOBJ
— возвращает название выделенного предмета в любом месте игры. Выделение предмета происходит в момент нажатия (щелчка мышью по предмету) и не снимается до применения команды unselect
.
Пример использования можно посмотреть в разделе $onobjsel
$STATTXT
$STATTXT
— возвращает текст, выведенный в окно дополнительного описания. Может быть полезна для замены части текста в окне дополнительного описания.
Пример:
p 'Вёз Корабль Карамель'
nl 'Наскочил Корабль На Мель'
$string = $stattxt
$STR
$STR
— возвращает строку текста, полученную переводом числа в строку. Общая запись:
$STR([#число])
Пример:
$str(56) & ! превратит число 56 в строку "56" и выведет на экран
$STRFIND
$STRFIND
— возвращает подстроку, соответствующую регулярному выражению, из указанной строки. Общая запись:
$STRFIND([$строка], [$шаблон], [#номер])
, где [$строка]
— исходная строка, в которой производим поиск вхождения, соответствующего регулярному выражению [$шаблон]
, или группе номер [#номер]
в регулярном выражении. Если подстрока с указанным номером отсутствует, то возвращается пустая строка. Нумерация групп подстрок начинается с 1. Если параметр [#номер]
отсутствует, или равен 0, то возвращается подстрока, соответствующая всему регулярному выражению [$шаблон]
.
Например, возьмём регулярное выражение:
^(\S+)\s(\S+)\s(\S+)$
Метасимвол \S
означает любой непробельный символ, а квантификатор +
указывает, что непробельные символы должны присутствовать один или более раз. Таким образом запись \S+
можно условно сопоставить слову. Каждое слово с помощью скобок ()
выделено в отдельную группу, а между группами присутствуют пробельные символы \s
. Метасимволы ^
и $
означают соответственно начало и конец строки. Таким образом наше регулярное выражение соответствует любой строке из трёх слов, разделённых пробелами.
Тогда:
! в этом случае строка не соответствует регулярному выражению
! потому что согласно регулярному выражению строка должна начинаться
! с группы непробельных символов. Команда вернёт пустую строку ''
$strfind(' идти к пещере','^(\S+)\s(\S+)\s(\S+)$')
! в данном случае строка полностью соответствует регулярному выражению
! а значит команда вернёт строку полностью 'идти к пещере'
$strfind('идти к пещере','^(\S+)\s(\S+)\s(\S+)$') = ''
! в следующих трёх примерах строка соответствует регулярному выражению
! однако третий аргумент указывает, какую именно группу из этого
! регулярного выражения мы хотим получить, поэтому каждая команда вернёт
! соответственно первое, второе и третье слова из строки
$strfind('идти к пещере','^(\S+)\s(\S+)\s(\S+)$', 1) & ! вернёт 'идти'
$strfind('идти к пещере','^(\S+)\s(\S+)\s(\S+)$', 2) & ! вернёт 'к'
$strfind('идти к пещере','^(\S+)\s(\S+)\s(\S+)$', 3) & ! вернёт 'пещере'
! здесь последняя группа непробельных символов объединена в одну
! группу с последним пробельным символом. Квантификатор "?" указывает,
! что эта группа может как присутствовать в строке, так и отсутствовать:
$strfind('идти к пещере', '^(\S+)\s(\S+)(\s(\S+))?$', 4) & ! вернёт 'пещере'
$strfind('идти к пещере', '^(\S+)\s(\S+)(\s(\S+))?$', 3) & ! вернёт ' пещере'
! этому же регулярному выражению соответствует и такая строка
$strfind('искать ключ', '^(\S+)\s(\S+)(\s(\S+))?$', 1) & ! вернёт 'искать'
! а вот эта строка уже не соответствует регулярному выражению
$strfind('искать', '^(\S+)\s(\S+)(\s(\S+))?$', 1) & ! вернёт ''
Следующие примеры показывают, как $strfind
возвращает часть строки, соответствующую регулярному выражению:
$strfind('идти к дому', 'к\s(\S+)') & ! вернёт 'к дому'
$strfind('идти к дому', 'к\s(\S+)', 1) & ! вернёт 'дому'
$strfind('идти к своему дому', 'к\s(\S+)', 1) & ! вернёт '