Операторы

Неявный оператор

Неявный оператор — это оператор, который не прописывается в коде QSP, но производит вывод значений на экран. Он подразумевается везде, где в команде присутствует выражение без оператора. Неявный оператор выводит в Окно основного описания значения таким же образом, как если бы вы использовали явное указание оператора *pl, то есть выводит значение и совершает переход на новую строку. Примеры:

$AAA + '989'
'Вы находитесь в парке'
'Преформатированная

    строка'
$curloc & ! выведет на экран название локации

В отличие от оператора *pl неявный оператор не выводит на экран пустую строку с переходом на новую строку, если ему не передаётся никакое значение. Это означает, что если функция не возвращает никакого значения, неявный оператор просто игнорируется. Пример:

# start
! это код локации, вызывающей локацию-функцию
$curloc
$func('foo')
$func('foo')
$curloc
- start

# foo
! это код локации-функции
local i = 0
- foo

В данном случае локация-функция foo ничего не возвращает, поэтому на экране мы увидим две строки со словом "start", между которыми не будет пустых строк, так как неявный оператор в строках с $func на локации start будет просто проигнорирован. Сравните с:

# start
! это код локации, вызывающей локацию-функцию
*pl $curloc
*pl $func('foo')
*pl $func('foo')
*pl $curloc
- start

# foo
! это код локации-функции
local i=0
- foo

! (комментарий)

! — оператор комментария. То, что находится в строке после оператора комментария, и до конца строки игнорируется интерпретатором. Оператор комментария позволяет "закомментировать" (выключить) ненужный временно оператор/функцию во время отладки игры. Кроме того, написание комментариев к коду программы является одним из признаков хорошего стиля программирования.

Необходимо чётко понимать, что это именно оператор, поэтому если вы комментируете некую строку кода, то ! должен стоять после &:

*pl "Hello, world!" & ! комментарий

Комментарии могут быть однострочными, то есть заканчиваться в той же строке, где стоит оператор комментария:

! однострочный комментарий
*pl "строка текста" & ! тоже однострочный комментарий

Исключение

Единственным исключением из этого правила является запись комментария после двоеточия в многострочных операторах:

act "Многострочное действие": ! комментарий
    *pl "Текст на экране"
end

Комментарии могут быть многострочными. Для этого после оператора комментария нужно записать кавычки, апострофы, или фигурные скобки. Например так:

! "это первая строка коммантария
    это вторая строка комментария
    это третья строка комментария
"

Многострочные комментарии могут принимать самые разнообразные формы:

! строка до  кавычек " текст внутри кавычек
может переходить на другие строки " а так же {
можно использовать другие группы символов, чтобы
продолжать многострочный комментарий
} и комментарий не кончится, пока не кончится строка

*CLEAR

*CLEAR — очищает окно основного описания. Имеет краткую форму *clr.

*NL

*NL — переход на новую строку, затем вывод текста в окне основного описания. Общая запись:

*NL [$текст]

, где [$текст] — любая строка текста, число, или выражение любого типа. Если [$текст] отсутствует, происходит просто переход на новую строку. Пример:

*p "Текст без перехода на новую строку."
*nl "Переход на новую строку + выведение текста."
*p "Текст без перехода на новую строку."

*P

*P — вывод текста в окно основного описания без перехода на новую строку. Вывод текста любым другим оператором сразу после *p добавит новый текст сразу после текущего. Общая запись:

*P [$текст]

, где [$текст] — любая строка текста, число, или выражение любого типа. [$текст] может быть пустой строкой '', но не должен отсутствовать. Пример:

*p "Текст без перехода на новую строку."
*p "Текст без перехода на новую строку."
*p ""
*p "Текст без перехода на новую строку."

*PL

*PL — вывод текста в окно основного описания, затем переход на новую строку. Общая запись:

*PL [$текст]

где [$текст] — любая строка текста, число, или выражение любого типа. [$текст] может отсутствовать, тогда просто переход на новую строку. Пример:

*pl "Вывод текста, затем переход на новую строку."
*pl "Вывод текста, затем переход на новую строку."
*p "Текст без перехода на новую строку."
*pl "Вывод текста, затем переход на новую строку."

Аналогичным образом можно вывести текст, просто написав нужное выражение вместо данного оператора. Например, строки:

*pl $AAA + '989'
*pl 'Вы находитесь в парке'
*pl 'Преформатированная

    строка'

и:

$AAA + '989'
'Вы находитесь в парке'
'Преформатированная

    строка'

сработают одинаково.

ACT

ACT — создаёт и выводит в окно действий новое действие.

Общая запись в однострочной форме:

ACT [$название], [$путь к файлу изображения]: [оператор] & [оператор] & [оператор]

Общая запись в многострочной форме:

ACT [$название], [$путь к файлу изображения]:
    [оператор]
    [оператор]
    [оператор]
END

К списку действий в окне действий добавляется новое с названием [$название] и изображением, которое лежит по пути [$путь к файлу изображения]. При нажатии на действие выполняются заданные операторы.

Параметр [$путь к файлу изображения] может отсутствовать, при этом действие добавится без изображения.

Примеры:

! действие в однострочной форме записи
act "Сорвать с берёзы яблоко": яблоко += 1 & *pl "Вы сорвали яблоко, спелое белое."

! действие в многострочной форме записи, с изображением
act "Сорвать арбуз с куста", "img/watermelon.png":
    арбуз += 1
    *pl "Вы сорвали арбуз с куста"
end

Если в списке действий уже есть действие с указанным названием, то новое действие не создаётся, и не заменяет собой уже существующее, плеер просто игнорирует команду act. Таким образом нельзя вывести действия с одинаковыми названиями. Пример:

act "Действие 1": *pl "Старое действие."
act "Действие 1": *pl "Новое действие."

Однако, вы можете сымитировать действия с одинаковыми названиями в режиме распознавания HTML, добавив в названия действий HTML-тег:

usehtml = 1
act 'Действие 1<a data-avs="uid-old"></a>': *pl "Старое действие."
act 'Действие 1<a data-avs="uid-new"></a>': *pl "Новое действие."

ADDOBJ

ADDOBJ — добавление нового предмета в окно предметов. Общая запись:

ADDOBJ [$название], [$путь к файлу изображения], [#позиция]

, где [$название] — это название предмета, [$путь к файлу изображения] — это путь к файлу изображения предмета (отображается рядом с названием предмета), а [#позиция] — на какое место в инвентаре добавляется предмет. Параметр [#позиция] может отсутствовать. По умолчанию предметы добавляются в конец списка. Нумерация предметов в инвентаре ведётся с 1. Параметр [$путь к файлу изображения] может отсутствовать, значение по умолчанию - '', при этом предмет добавляется без изображения.

Устаревшая форма записи:

ADD OBJ [$название],[$путь к файлу изображения],[#индекс]

!!! Не используйте данную форму записи. Её поддержка прекратится в новых версиях плеера.

Можно добавлять предметы с одинаковым названием, однако если вы планируете добавлять много одинаковых предметов, то лучше использовать дополнительную переменную для подсчёта этих предметов, а в окно предметов добавить один предмет, чтобы не загромождать инвентарь списком из 137 предметов Рубль / Патрон:

if obj('Патроны'):
! если предмет "Патроны" уже добавлен, просто увеличиваем их число
    патроны += 10
else
! если предмет "Патроны" ещё не добавлен, добавляем, и увеличиваем число
    addobj 'Патроны'
    патроны += 10
end

Для хранения числа предметов можно использовать массивы, индексируемые через строки:

objects['деньги'] = 12
objects['патроны'] = 137
'Количество: <<objects[$getobj(countobj)]>>'

Пример добавления предмета в самый верх списка (при этом все остальные предметы сместятся вниз):

addobj "Отвёртка", "", 1

CLA

CLA - очистка списка текущих действий (удаление всех действий из окна действий).

CLEAR

CLEAR — очищает окно дополнительного описания. Имеет краткую форму clr.

CLOSE

CLOSE — останавливает проигрывание указанного звукового файла. Общая запись:

CLOSE [$путь к звуковому файлу]

, где [$путь к звуковому файлу] — путь к звуковому файлу относительно файла игры. Если параметр [$путь к звуковому файлу] не указан, происходит остановка воспроизведения всех звуковых файлов.

CLOSE ALL

CLOSE ALL — остановка проигрывания всех активных звуковых файлов. Имеет краткую форму close.

CLS

CLS — очищает все окна кроме списка предметов. Эквивалентно конструкции:

clear & *clear & cla & cmdclear

CMDCLEAR

CMDCLEAR — очистка строки ввода. Имеет краткую форму cmdclr.

COPYARR

COPYARR — копирование содержимого одного массива в другой. Общая запись:

COPYARR [$приёмник], [$источник], [#начало], [#количество]

, где: [$приёмник] — это массив, в который производится копирование, размер и наполнение значения не имеют; [$источник] — это массив, из которого производится копирование; [#начало] — номер элемента, с которого нужно начинать копирование; [#количество] — сколько элементов нужно скопировать. Параметр [#количество] является необязательным; по умолчанию — до конца массива-источника. Параметр [#начало] является необязательным; по умолчанию — 0.

Примеры:

! копируем все элементы массива '$b' в массив '$a'
copyarr '$a', '$b'
! при этом так же были скопированны все элементы массива 'b' в массив 'a'

! копируем в массив 'c' элементы массива 'd', начиная с шестого
copyarr 'c', 'd', 6

! копируем шесть первых элементов массива 'd' в массив 'c'
copyarr 'c', 'd', 0, 6

В силу особенностей плеера при копировании, например, числового массива mass1 в mass2 копируется также текстовый массив $mass1 в $mass2.

Другие примеры:

copyarr $arrname1, $arrname2, 10, 5
copyarr 'a<<$arrname1>>', 'a<<$arrname2>>'

DELACT

DELACT — удаляет действие из списка действий (если такое действие существует). Общая запись:

DELACT [$название]

, где [$название] — название действия, которое хотим удалить.

Примеры:

! удаляем действие с конкретным названием
delact 'Идти вперед'
! удаляем выделенное действие
delact $selact

Устаревшая форма записи:

DEL ACT [$название]

!!! Не используйте данную форму записи. Её поддержка прекратится в новых версиях плеера.

DELOBJ

DELOBJ — удаление предмета из инвентаря по названию (если такой предмет существует). Общая запись:

DELOBJ [$название]

, где [$название] — название предмета, который хотим удалить.

Если в инвентаре присутствуют одинаковые предметы, команда удалит самый верхний с указанным индексом.

Примеры:

! удаляем предмет с конкретным названием
delobj "Отвёртка"
! удаляем выделенный предмет
delobj $selobj

Устаревшая форма записи:

DEL OBJ [$название]

!!! Не используйте данную форму записи. Её поддержка прекратится в новых версиях плеера.

DYNAMIC

DYNAMIC — выполняет код, переданный в виде строки текста. Общая запись:

    DYNAMIC([$код], [аргумент 0], [аргумент 1], ... , [аргумент 18])

, где [$код] — это обычный код QSP, записанный в виде текста. Выполнение такого кода аналогично выполнению кода оператора GOSUB. Аргументы [аргумент 0], [аргумент 1] и т.д. могут использоваться внутри [$код], их значения автоматически помещаются в переменные args[0], args[1], и т.д. соответственно. После выполнения старые параметры args восстанавливаются, затем продолжается выполнение кода со следующей команды после dynamic.

Примеры:

dynamic '$a = "string<<$b>>"'
dynamic '$a'
dynamic 'if $a = "string": "text!"'
dynamic "
    $args[0]
    addobj $args[1]
", 'Текст', 'Вилка'

Нижеследующая информация справедлива и для функции dyneval.

Важно! Если код задан с помощью апострофов ('') или кавычек (""), в тексте вычисляются подвыражения:

$args[0] = 'qwerty'
$code = '
    *pl "<<$args[0]>>"
    *pl $args[0]
'

dynamic $code, 'asdfg'

В этом случае при задании переменной $code будет вычислено подвыражение, поэтому первой строкой выведется 'qwerty', второй строкой выведется 'asdfg'.

Фигурные скобки - третий вид кавычек используемый специально для написания динамического кода. Здесь поддерживается вложенность скобок, а перед выполнением кода не вычисляются подвыражения:

$args[0]='qwerty'
$code = {
    *pl "<<$args[0]>>"
    *pl $args[0]
}

dynamic $code, 'asdfg'

В этом случае будут выведены две строки 'asdfg'.

EXIT

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

В качестве блока кода может выступать локация, действие, код, переданный dynamic'у или dyneval'у, или код в гиперссылке.

Пример:

if args[1] = 0:
    exit
else
    if args[0] mod args[1] = 0:
        result = 1
    else
        result = 0
    end
end

Внимание!!!

В плеерах версии 5.8.0 появился оператор цикла loop.

Тело цикла так же считается отдельным блоком кода, однако оператор exit прерывает не только сам цикл, но и блок кода, в котором находится цикл.

FREELIB

FREELIB — удаляет все локации, добавленные с помощью оператора inclib.

5.7.0

В старых версиях плеера команда называлась dellib и killqst.

GOSUB

GOSUB — выполнение кода указанной локации без непосредственного перехода на неё.

Общая запись:

GOSUB [$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 8]

, где [$локация] — это название локации, код которой мы хотим выполнить без непосредственного перехода на неё. Аргументы [аргумент 0], [аргумент 1] и т.д. могут использоваться на этой локации, их значения автоматически помещаются в переменные args[0], args[1], и т.д. соответственно. После обработки локации предыдущие значения args восстанавливаются. Использование аргументов не обязательно.

При обращении к локации по gosub базовое описание локации добавляется к текущему описанию, базовые действия добавляются к текущим действиям, и происходит выполнение операторов в поле "Выполнить при посещении", затем возврат на исходную строку (продолжение выполнения кода после gosub).

Примеры вызова локаций по gosub:

!обработка локации "ход". Массив args[] пуст.
gosub 'ход'

!обработка локации с названием из переменной $location
!Передаётся один параметр - args[0] равен 1.
gosub $location,1

!обработка локации "ход" с передачей 3-х параметров.
! $args[0] = $var (значению), args[1] = 2,
! $args[2] = "данные". Обратите внимание на символы '$'.
gosub 'ход',$var,2,'данные'

Ещё пример:

! это код вызова локации "переход"
gosub 'переход', 'локация'

! а это код самой локации "переход"
# переход
*pl $args[0]  & ! на экран выведется текст 'локация'
! в окне действий появится новое действие:
act 'перейти':
    goto "улица"
end
- переход

Оператор имеет краткую форму gs:

GS [$локация], [аргумент 0], [аргумент 1], ... , [аргумент 18]

GOTO

GOTO — переход на указанную локацию. Общая запись:

GOTO [$локация], [аргумент 0], [аргумент 1], ... , [аргумент 18]

, где [$локация] — название локации, на которую должен быть осуществлён переход. Аргументы [аргумент 0], [аргумент 1] и т.д. могут использоваться на этой локации, их значения автоматически помещаются в переменные args[0], args[1], и т.д. соответственно. Использование аргументов не обязательно.

При переходе на новую локацию при помощи goto очищается окно основного описания, а также список текущих действий, затем в окно основного описания выводится текст базового описания, в окно действий — базовые действия, а так же выполняется код из поля "Выполнить при посещении" локации [$локация]. Так же при переходе на новую локацию изменяется значение, возвращаемое функцией $curloc.

Примеры:

! переход на локацию "дом".
! Массив args на локации "дом" будет пуст.
goto 'дом'

! переход на локацию "улица" с передачей 2-х параметров.
! на локации "улица" args[0] равен 1,
! $args[1] содержит строку "данные".
goto 'улица',1,'данные'

Оператор имеет краткую форму gt:

GT [$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 8]

IF

IF — основной оператор для записи конструкций условий. Конструкции, записываемые с помощью этого оператора (назовём их "простыми условиями"), имеют две формы: однострочную и многострочную, — и в общем виде выглядят так:

Общая форма записи:

! однострочная форма записи
IF [#выражение]: {команда 1} & {команда 2} & ...

! многострочная форма записи
IF [#выражение]:
  {команда 1}
  {команда 2}
  ...
END

В данном случае, если верно условие [#выражение], выполняются команды {команда 1}, {команда 2} и т.д.

• Для однострочной формы записи это будут только те команды, которые идут в той же строке, что и оператор IF до конца строки;
• а для многострочной формы записи это будут те команды, которые идут в последующих строках после двоеточия и до специального ключевого слова END.

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

Ключевое слово END при многострочной форме записи должно стоять отдельной строкой.

Если условие [#выражение] не верно, команды выполнены не будут.

Примеры однострочной формы записи условий:

! если сумма a и b равна двум,
! переменной c присваивается значение 30
if a + b = 2: c = 30
! Если в инвентаре нет апельсина, выводится текст
if no obj("Апельсин"): pl "У Вас нет апельсина."
! это тоже простая однострочная форма
if ((a+b)/c)=45+54 or (b<5 or c>45) and no obj 'лопата' and $f=$vvv+'RRRRR': p 'OK' & goto 'Next'

Примеры многострочной формы записи условий:

if библиотека = 0:
  узнал_о_тусовке = 0
  библиотека_вернулся = 1
  gt 'библиотека'
end
if a+b=2:
  c=30
end

Обратите внимание!!!

При многострочной форме записи после двоеточия в той же строке, в какой находится оператор IF, не должны идти никакие команды, иначе плеер посчитает такой оператор условия однострочным, и команды в последующих строках будут выполняться в любом случае, независимо от того, верным окажется условие или нет. Пример такой ошибочной записи:

if библиотека = 0: узнал_о_тусовке = 0
  библиотека_вернулся = 1 &! эта строчка будет выполняться в независимости от верности условия
  gt 'библиотека' &! и эта
end &! ключевое слово end - просто игнорируется

Исключением является оператор комментария записанный после двоеточия:

if библиотека = 0: ! если не посещал библиотеку
  узнал_о_тусовке = 0
  библиотека_вернулся = 1
  gt 'библиотека'
end

Но в случае, если комментарий отделён амперсандом, условие будет считаться однострочным:

if библиотека = 0: & ! такой комментарий делает условие однострочным!
  узнал_о_тусовке = 0 & ! эта строчка будет выполняться в независимости от верности условия
  библиотека_вернулся = 1 & ! и эта
  gt 'библиотека' &! и эта тоже
end &! ключевое слово end - просто игнорируется

Для многострочных форм записи допускается вложенность неограниченной глубины. Каждый уровень вложения должен заканчиваться своей строкой end.

Примеры:

if a+b<3 or y=8:
    p 'A+B<3 или Y=8'
    nl
    if j=88: nl & p 'NEXT'
    if $h='ooo':
        p 'loo' & jump 'lll'
    end
end

if a=0:
    'abc1234'
    if b=0: '0' else '1'
    if j=88: nl & p 'NEXT'
    if $h='ooo':
        p 'loo' & jump 'lll'
    else
        p 'sample text'
        v=8
    end
    1234
else
    '01234'
    g=78
end

Несколько примеров неверной записи:

! в этом случае, если условие не будет выполнено,
! плеер проигнорирует только команду `k1=34`
! поскольку посчитает, что это однострочное условие
if abcd=3: k1=34
    k2=35 & ! эта команда будет выполняться всегда
    k3=36 & ! эта комнада будет выполняться всегда
end & ! этот end будет проигнорирован

! данная строка выведет ошибку неизвестное действие
! так как однострочные формы записи не должны оканчиваться end`ом
if abcd=3: k1=34 else k1=25 end

ELSE

ELSE — ключевое слово, использующееся совместно с оператором IF, и которое служит для предоставления альтернативы, если условие не выполнено. Ключевое слово ELSE так же имеет две формы записи: однострочную и многострочную.

• Многострочную форму записи ELSE можно использовать только в многострочной конструкции оператора IF,
• однострочную форму записи можно использовать как в однострочной, так и в многострочной, конструкции оператора IF. Общая форма записи:

! однострочная форма записи
IF [#выражение]: {команда д1} & {команда д2} & ... ELSE {команда н1} & {команда н2} & ...

! в многострочном IF:

! многострочная форма ELSE
IF [#выражение]:
    {команда д1}
    {команда д2}
    ...
ELSE
    {команда н1}
    {команда н2}
    ...
END

! однострочная форма ELSE
IF [#выражение]:
    {команда д1}
    {команда д2}
    ...
ELSE {команда н1} & {команда н2} & ...
    ! команды в следующих строках
    ! до END игнорируются
END

Здесь, если условие[#выражение] верно, выполняются команды от двоеточия до ключевого слова ELSE, а если условие [#выражение] не верно, выполняются команды от ключевого слова ELSE и до конца конструкции условия.

После ELSE можно ставить, а можно не ставить двоеточие.

При однострочной форме записи:

• и команды и ключевое слово ELSE должны быть записаны в одной строке
• окончанием альтернативного списка команд является конец строки.
• если однострочная форма записи ELSE используется в многострочной форме записи IF, все команды, которые идут в последующих строках после ELSE до END игнорируются.

Примеры однострочной записи:

! если сумма a и b равна двум, переменной c присваивается значение 30
! в противном случае (то есть если сумма a и b не равна двум)
! переменной c присваивается значение 10
if a+b=2: c=30 else c=10

! в зависимости от того есть ли в инвентаре апельсин
! выводится соответствующий текст
if obj("Апельсин"): pl "У Вас есть апельсин." else pl "У Вас нет апельсина."

! однострочная форма else внутри многострочной if
if $левая_рука = 'Великий меч':
  gosub 'atack', 300
  gosub 'health.prove'
  gosub 'win.prove'
else gosub 'atack', atack_power
end

При многострочной форме записи:

• все команды должны идти в последующих строках после ELSE;

Примеры многострочной записи:

if a+b=2:
  c=30
else
  c=10
end

if obj("Апельсин"):
  pl "У Вас есть апельсин."
else
  pl "У Вас нет апельсина."
end

if len($curtoken) > 0:
  $tokens[curtoken_num] = $curtoken tokens_count = curtoken_num + 1
else
  tokens_count = curtoken_num
end

ELSEIF

ELSEIF — ключевое слово, которое используется совместно с оператором IF и позволяет определять на одном уровне вложенности последовательно-исключающие условия. Имеет однострочную и многострочную формы записи.

• Многострочную форму записи можно использовать только в многострочных конструкциях с оператором IF,
• однострочную — как в многострочных, так и в однострочных конструкциях с оператором IF.

Общие формы записи:

! однострочная в однострочном условии
IF [#выражение 1]: {набор команд 1} ELSEIF [#выражение 2]: {набор команд 2} ELSE {последний набор команд}

! многострочная в многострочном условии
IF [#выражение 1]:
  {набор команд 1}
  ...
ELSEIF [#выражение 2]:
  {набор команд 2}
  ...
ELSEIF ... :
  ...
ELSE
  {последний набор команд}
  ...
END

! однострочная в многострочном условии
IF [#выражение 1]:
  {набор команд 1}
  ...
ELSEIF [#выражение 2]: {набор команд 2}
ELSEIF ... : ...
ELSE {последний набор команд}
END

Работает это следующим образом. Если [#выражение 1] верно, выполняются команды {набор команд 1}. Если [#выражение 1] неверно, но верно [#выражение 2], выполняются команды {набор команд 2}, и т.д. И только если неверны все выражения в текущей конструкции условия, выполнятся команды после ELSE. Верность выражения [#выражение 1] не исключает верности выражения [#выражение 2], однако верность выражения [#выражение 2] исключает верность выражения [#выражение 1].

Особенности записи ELSEIF:

• Может использоваться вариант написания ELSE IF. Работает точно так же.
• Если в многострочной конструкции IF после ELSEIF операторы идут в той же самой строке (однострочная форма), то все последующие строки игнорируются до следующего ELSEIF, либо до ELSE или END.
• В конструкции IF c ELSEIF может как присутствовать, так и отсутствовать часть с ELSE.

Примеры:

if obj('Зелье здоровья'): health += 100 esleif obj('Яблоко'): health += 15 else *pl 'Нечем пополнить силы!'

IF ОЧКИ>124:
  GOTO 'КОН3'
ELSEIF ОЧКИ>99:
  GOTO 'КОН4'
ELSE
  GOTO 'КОН5'
END

if money mod 10=1 and money mod 100<>11:
  *pl "У вас <<money>> монета."
elseif money mod 10>1 and money mod 10<5 and (money mod 100<5 or money mod 100>20):
  *pl "У вас <<money>> монеты."
elseif money mod 10=0 or money mod 10>4 or (money mod 100>10 and money mod 100<21):
  *pl "У вас <<money>> монет."
end

Пример записи ELSEIF с операторами в той же строке:

! реализация switch/case на QSP
if r = 0:
  'Вариант 0'
  elseif r = 1: 'Вариант 1'
  elseif r = 2: 'Вариант 2'
  elseif r = 3: 'Вариант 3'
  else: 'Без вариантов'
end

На заметку:

Для улучшения читаемости кода рекомендуется использовать конструкции с elseif только в многострочной форме оператора if.

INCLIB

INCLIB — из заданного файла игры добавляет все локации, названия которых отсутствуют среди текущих игровых локаций. Загруженные локации полностью эквивалентны локациям из основного файла игры. Общая запись:

INCLIB [$путь к файлу игры]

Пример:

inclib "lib/easy.math.qsp"
inclib "lib/easy.title.qsp"
inclib "res/drive.qsp"
inclib "res/base.qsp"
inclib "res/intro.qsp"

5.7.0

В более старых версиях плееров команда называлась addqst и addlib.

JUMP

JUMP — переход в текущем блоке кода на указанную метку. Общая запись:

JUMP [$метка]

, где [$метка] — это метка ниже или выше по коду (см. раздел "Метки").

jump находит метку только в пределах текущего блока кода, то есть метки локальны.

Отдельными блоками кода в QSP являются:

• код "Выполнить при посещении" конкретной локации (каждая локация - отдельный блок кода),
• код действия даже если действие добавлено программно,
• код в гиперссылке,
• код DYNAMIC/DYNEVAL

Пример:

jump 'КонеЦ'
p 'Это сообщение не будет выведено'
:конец
p 'А это сообщение пользователь увидит'

5.7.0

С помощью оператора jump в старых версиях плеера можно было организовывать циклы:

:loop
if s<9:
    s=s+1
    pl s
    jump 'loop'
end
p 'Всё!'

Двойной цикл с одной меткой:

:loop
if y<9:
    if x<9:
        *p "<<x>> - "
        x=x+1
        jump 'loop'
    end
    *pl ":<<y>>"
    y=y+1
    x=0
    jump 'loop'
end

Начиная с версии 5.8.0 для циклов введён собственный оператор loop.

KILLALL

KILLALL — уничтожает все переменные и удаляет все предметы из окна предметов. Эквивалентен конструкции:

killvar & killobj

Внимание!

Следует помнить, что killall не эквивалентен конструкции:

killobj & killvar

поскольку в этом случае значения переменных удаляются после удаления предметов, а значит код локации-обработчика удаления предметов успевает выполниться (см. $onobjdel).

Обычно killall используют в начале игры, если в конце игры предусмотрено действие "Начать заново".

KILLOBJ

KILLOBJ — удаление предмета, расположенного в заданной позиции. Общая запись:

KILLOBJ [#номер]

, где [#номер] — номер предмета в окне инвентаря. Нумерация предметов начинается с 1. Если параметр [#номер] не указан, удаляются все предметы. При удалении каждого предмета с помощью killobj, происходит выполнение кода локации-обработчика удаления предметов (см. $onobjdel).

Пример:

! удаляем самый верхний предмет в списке
killobj 1
! удаляем самый нижний предмет в списке
killobj countobj
! удаляем все предметы
killobj

KILLVAR

KILLVAR — удаление указанного элемента массива. Общая запись:

KILLVAR [$название массива], [индекс элемента]

, где [$название массива] — название массива, из которого хотим удалить элемент, а [индекс элемента] — номер, текстовый индекс, или многомерный индекс элемента в массиве, который хотим удалить. Нумерация элементов массивов начинается с 0.

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

Примеры:

killvar 'a', 3 & ! удалит из массива 'a' элемент с индексом 3.
killvar 'unit', 'Десантник' & ! удаляет из массива элемент с индексом 'Десантник'
killvar 'a' & ! удаляет массив 'a'
killvar & ! удаляет все переменные, массивы
killvar '$map_cell', (3, 4) & ! удаление по многомерному индексу

При удалении элемента все следующие за ним элементы сдвигаются на позицию вверх.

Пример:

a[0] = 4
a[1] = 3
a[2] = 23
a[3] = 15
KILLVAR 'a', 1
! теперь массив выглядит так:
! a[0] = 4
! a[1] = 23
! a[2] = 15

LET

LET — устаревший оператор для установки значений переменных. Общая запись:

LET [название переменной] = [выражение]
LET [переменная 1], [переменная 2], ... = [значение 1], [значение 2], ...

, где [название переменной] — это допустимое имя переменной, [выражение] — это допустимое для данной переменной значение.

• Названия числовых переменных записываются без символов $ и % в начале.
• Названия текстовых переменных записываются с символом $ в начале.
• Названия переменных, содержащих кортежи, записываются с символом % в начале.

Примеры:

! задаём текстовую переменную
let $text = "text string"
! задаём числовую переменную
let abs = 123
! задаём кортеж
let %tuple = [123, "text string"]
! множественное присваивание
let unit_power, $unit_name = 1300, 'DiggerBull'
! распаковка кортежа
let $name, age, height = %npc_fields

подсказка

Данный оператор считается устаревшим. Используйте вместо него оператор set, и только в тех случаях, когда это улучшит читаемость кода.

! присвоение можно проводить без операторов `set` или `let`:
$text = "text string"

LOCAL

LOCAL — объявляет локальную переменную (или несколько переменных) в текущем блоке кода.

Общая запись:

LOCAL [переменная 1], [переменная 2], ...
LOCAL [переменная 1], [переменная 2], ... = [значение 1], [значение 2], ...

, где [переменная 1], [переменная 2] и т.д. — это имена переменных/массивов, записанные прямо (не в кавычках), а [значение 1], [значние 2] и т.д. — любые значения, константы, значения выражений, функций или других переменных.

Число переменных и значений должно совпадать (кроме случаев распаковки).

! объявляем одну локальную переменную
local tempora = 12
! объявляем несколько локальных переменных
local x, y, $item = 11, 19, "Старый меч"
! объявляение с распаковкой
local i, j = %map_cell
local z, $a = [13, '37']

В отличие от операторов set и let переменную можно объявить, но значение ей не присваивать.

local tempora
local x, y, $item, %map_cell

При этом, несмотря на то, что переменная создаётся, arrsize для неё будет возвращать 0. Т.е. проверить, объявлена ли переменная нельзя.

local arr
*pl arrsize('arr') & ! выведет 0

Собственные локальные переменные можно создавать в следующих блоках кода:

• Локации сами по себе.
• Код, передаваемый оператору DYNAMIC, или функции DYNEVAL, в виде текста.
• Код, выполняемый при нажатии на гиперссылку.
• Код каждого отдельного Действия (ACT).
• Код каждого отдельного Цикла (LOOP)

Внимание!

У локальных переменных есть одна особенность, которую нужно очень чётко понимать. Значение объявленной в данном блоке кода локальной переменной транслируется и во все вложенные, или вызванные из данного, блоки кода. Например, если на локации объявлена локальная переменная, то её значение транслируется во все вызываемые с помощью GOSUB или FUNC локации, в блоки кода для DYNAMIC/DYNEVAL, в блоки циклов и так далее. Пример:

# start
! из этой локации мы будем вызывать локацию foo
i = 99 & ! объявляем глобальную переменную
gosub 'foo'
*nl i & ! на экране увидим число 99
--- start ---

# foo
! на этой локации объявляем локальную переменную
local i = 0
! локальная переменная транслируется в цикл
loop while i < 10 step i += 1:
    ! в цикле мы вызываем локацию undo
    gosub 'undo'
    ! и так же в цикле мы работаем с переменной,
    ! объявленной на локации foo
end
*nl i & ! на экране увидим число 10
--- foo ---

# undo
! в эту локацию из цикла с локации foo
! транслируется всё та же локальная переменная
! объявленная на локации foo
i+=1 & ! увеличиваем значение переменной, влияя на значение в foo
*p 'undo:<<i>>, ' & ! на экране появятся числа 1,3,5,7,9 с припиской undo:
--- undo ---

Однако! Значения локальных переменных не транслируются в действия (в отличие от значений массива ARGS на текущей локации):

$args[0] = 'текущая локация'
local $var = 'локальная переменная'
*pl $args[0]
*pl $var
act "Вывести значения":
    *pl $args[0]
    *pl $var
end

Примеры назначения локальных переменных

Две локации, на каждой из которых собственная переменная i

# локация 1
if i = 0: i = 99 & ! значение переменной i задаётся лишь раз
*pl "Глобальное i = <<i>>"
act "На локацию 2": goto 'локация 2'
--- локация 1 ---

# локация 2
*pl "Глобальное i = <<i>>"
local i = 137 & ! значение переменной i задаётся лишь раз
*pl "Локальное i = <<i>>"
act "На локацию 1": goto 'локация 1'
--- локация 2 ---

Ещё пример с двумя локациями

! этот код последовательно выведет на экран числа 12, 549 и 99, 549
# start
x = 99
z = 4608
gosub 'foo'
*pl x & *pl z   & ! на экран выведутся числа 99 и 549
--- start ---

# foo
local x & ! объявляем переменную x локальной для данной локации
x = 12    & ! изменяем значение переменной x
z = 549
*pl x & *pl z   & ! на экран выведутся числа 12 и 549
--- foo ---

Пример объявления локальных переменных в коде для DYNEVAL и в цикле

$chkObjWord = {
    ! это код, записанный в виде текста в переменную $chkObjWord
    ! в локальную переменную $word записываем слово,
    ! по которому производим поиск
    local $word = $args[0]
    loop local i = 1 while no i > countobj step i += 1:
        ! используем локальную переменную i внутри цикла
        ! цикл выполняется пока счётчик не превысит число предметов
        if instr($getobj(i), $word) <> 0:
            ! как только в названии очередного предмета
            ! встречается рассматриваемое слово
            result = i  & ! возвращаем позицию
            exit    & ! закрываем функцию
        end
    end
}
object_position = dyneval($chkObjWord, 'граната')

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

i=99
act "Действие с локальной i":
    local i = 449933
    *pl i
end
act "Действие с глобальной i":
    *pl i
end

LOOP

LOOP — оператор цикла. Необходим для организации циклических вычислений. Общая запись однострочной формы:

LOOP {команды до начала цикла} WHILE [условие] STEP {команды в конце итеррации}: {операторы тела цикла}

Общая запись многострочной формы:

LOOP {команды до начала цикла} WHILE [условие] STEP {команды в конце итеррации}:
    {операторы тела цикла}
END

, где:

• {команды до начала цикла} — это команды, выполняемые до того, как цикл будет запущен. Данные команды относятся к блоку цикла, но не попадают в итерации (проходы), т.е. выполняются только один раз. Здесь можно, например, объявить счётчик цикла. И здесь можно писать множество команд, перечисляя их через разделитель & (амперсанд).
• [условие] — это выражение, по значению которого проверяется условие. Здесь могут использоваться операции сравнения и логические операции в любых связках. В случае, если значение выражения [условие] равно нулю, цикл прерывается.
• {команды в конце итеррации} — это команды, выполняемые в конце каждого прохода цикла. Сюда можно помещать команды, которые не относятся напрямую к телу цикла, но тем не менее должны быть выполнены на каждой итерации. Здесь можно, например, изменять значение счётчика цикла. И здесь можно писать на самом деле множество команд, перечисляя их через разделитель & (амперсанд).
• {операторы тела цикла} — это команды, которые необходимо выполнять на каждом проходе, и являющиеся основными для цикла. То есть мы делаем цикл именно ради этих команд.

Цикл в QSP является отдельным блоком кода, и это значит, что внутри этого блока кода мы можем объявить локальные переменные. Это очень удобно, потому что мы можем объявить локальную переменную для счётчика, и это не повлияет на остальные переменные на локации:

i = 99
*pl "i до цикла <<i>>"
loop local i = 0 & *p "i в цикле: " while i < 6 step i += 1:
    *p "<<i>>, "
end
*nl "i после цикла <<i>>"

Циклы очень удобно использовать для перебора массивов. Например, с помощью цикла можно сложить все числа, хранящиеся в массиве:

summ=0 & ! сюда будем записывать сумму чисел
! наши числа лежат в массиве **mass**
loop local i, size = 0, arrsize('mass') while i < size step i += 1:
    summ += mass[i]
end
*pl 'Сумма всех элементов массива mass: <<summ>>'

MENU

MENU — в любом месте игры выводит на экран всплывающее меню, пункты которого прописаны в указанном массиве. Общая запись:

MENU [$название массива]

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

["название пункта меню", "название локации", "путь к файлу иконки"]

Название пункта меню — это то, что мы увидим на экране, когда меню будет выведено; название локации — это название локации, код которой будет выполняться при щелчке на соответствующем пункте меню; путь к файлу иконки — это путь к файлу изображения, которое будет выведено рядом с названием пункта меню.

Зная это, мы можем заполнить массив для того, чтоб создать наши пункты меню:

%stone[0] = ['Взять камень', 'takestone']
%stone[1] = ['Кинуть камень', 'throwstone']
%stone[2] = ['Осмотреть камень', 'lookstone']

Здесь название массива (%stone) - это название меню, а кортежи - действия, для которых указаны названия пунктов и названия локаций-обработчиков выбора пунктов меню. При выборе пункта "Взять камень" произойдёт вызов локации с названием "takestone". Аналогично будет происходить с другими пунктами.

Чтобы вывести меню на экран, нужно воспользоваться оператором MENU:

menu '%stone'

Пример создания меню с иконками:

! нет иконки
%usr_menu[0] = ['Взять предмет', 'take_item']
! иконка задана gif-файлом
%usr_menu[1] = ['Положить предмет', 'put_item', 'images/put_item.gif']
! иконка задана значением $icon_file
%usr_menu[2] = ['Уничтожить предмет','del_item', $icon_file]
! пункт меню задан 3-мя переменными
%usr_menu[3] = [$name, $location, $icon_file]

menu 'usr_menu' &! покажет меню из 4-х пунктов

Меню заканчивается на элементе массива со пустым кортежем, либо с кортежем, в котором отсутствует значение для названия пункта меню или локации-обработчика пункта меню.

Примеры, когда два последних пункта меню не будут созданы:

%usr_menu[0]=['Взять предмет','take_item'] & ! этот пункт мы увидим на экране
$usr_menu[1]=['Осмотреть предмет','look_item'] & ! и этот пункт мы увидим на экране
$usr_menu[2]=[] & ! пустой кортеж, плеер посчитает, что меню кончилось
$usr_menu[3]=['Положить предмет','put_item'] & ! этот пункт мы не увидим

%usr_menu[0]=['Взять предмет','take_item'] & ! этот пункт мы увидим на экране
$usr_menu[1]=['Осмотреть предмет','look_item'] & ! и этот пункт мы увидим на экране
$usr_menu[2]=['уничтожить предмет', ''] & ! не указана локация-обработчик, пункт не увидим
$usr_menu[3]=['Положить предмет','put_item'] & ! и этот пункт мы не увидим

%usr_menu[0]=['Взять предмет','take_item'] & ! этот пункт мы увидим на экране
$usr_menu[1]=['Осмотреть предмет','look_item'] & ! и этот пункт мы увидим на экране
$usr_menu[2]=['', 'del_item'] & ! не указано название, пункт не увидим
$usr_menu[3]=['Положить предмет','put_item'] & ! и этот пункт мы не увидим

Чтобы вставить разделитель в меню, используйте кортеж со значениями -. Т.е. если нужно поставить разделитель вместо 3-го элемента:

%usr_menu[0]=['Взять предмет','take_item']
$usr_menu[1]=['Осмотреть предмет','look_item']
$usr_menu[2]=['-', '-'] & ! разделитель вместо пункта меню
$usr_menu[3]=['Положить предмет','put_item']

В локацию-обработчик выбора пункта меню передаётся аргумент (args[0]) - позиция выбранного пункта. Позиции элементов меню нумеруются с 1.

Устаревший вариант заполнения массива меню. Строки

Этот вариант можно использовать, как в плеерах версии 5.9.0, так и в более ранних версиях.

Здесь пункты меню — это строковые значения массива с особым форматом записи:

"название пункта меню:название локации:путь к файлу иконки"

• Название пункта меню — это то, что мы увидим на экране, когда меню будет выведено;
• название локации — это название локации-обработчика пункта меню, код которой будет выполняться при щелчке на соответствующем пункте меню;
• путь к файлу иконки — это путь к файлу изображения, которое будет выведено рядом с названием пункта меню. Если путь к файлу иконки не указан или указанный файл недоступен, то пункт меню отобразится без иконки.

Поиск символов ":" начинается с конца строки, то есть название пункта меню может содержать двоеточия, однако тогда обязательно после названия локации должно стоять двоеточие, даже если вы не используете иконки для пунктов меню.

$stone[0]='Камень: взять:takestone:'
$stone[1]='Камень: кинуть:throwstone:'
$stone[2]='Камень: осмотреть:lookstone:'

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

Таким образом мы должны заполнить массив для того, чтоб создать наши пункты меню:

$stone[0]='Взять камень:takestone'
$stone[1]='Кинуть камень:throwstone'
$stone[2]='Осмотреть камень:lookstone'

Здесь название массива ($stone) - это название меню, а текстовые значения массива - действия, для которых указаны названия и названия локаций-обработчиков выбора пунктов меню. При выборе пункта "Взять камень" произойдёт обработка локации с названием "takestone". Аналогично будет происходить с другими пунктами.

Чтобы вызвать меню на экран нужно воспользоваться оператором menu:

menu '$stone'

Меню можно вызывать в любом месте игры, например, из гиперссылок:

'<a href="EXEC: menu `$stone`">Камень</a>'

Пример создания меню с иконками:

! нет иконки
$usr_menu[0] = 'Взять предмет:take_item'
! иконка задана gif-файлом
$usr_menu[1] = 'Положить предмет:put_item:images/put_item.gif'
! иконка задана значением $icon_file
$usr_menu[2] = 'Осмотреть предмет:look_item:<<$icon_file>>'
! пункт меню задан 3-мя переменными
$usr_menu[3] = '<<$name>>:<<$location>>:<<$file>>'

menu 'usr_menu' &! покажет меню из 4-х пунктов

Меню заканчивается на элементе массива со значением '' (пустая строка). Т.е. если массив меню состоит из элементов 'Взять', 'Осмотреть', '', 'Бросить', то 2 последних пункта меню не будут созданы:

$usr_menu[0] = 'Взять предмет:take_item' & ! этот пункт мы увидим на экране
$usr_menu[1] = 'Осмотреть предмет:look_item' & ! и этот пункт мы увидим на экране
$usr_menu[2] = '' & ! здесь пустое значение, плеер посчитает, что меню кончилось
$usr_menu[3] = 'Положить предмет:put_item' & ! этот пункт мы не увидим

Чтобы вставить разделитель в меню, вместо соответствующего элемента массива напишите "-:-". Т.е. если нужно поставить разделитель вместо 3-го элемента:

$usr_menu[0] = 'Взять предмет:take_item'
$usr_menu[1] = 'Осмотреть предмет:look_item'
$usr_menu[2] = '-:-'
$usr_menu[3] = 'Положить предмет:put_item'

MSG

MSG — вывод указанного сообщения в диалоговом окне. Общая запись:

MSG [сообщение]

, где [сообщение] — любая строка текста, число, выражение любого типа. Примеры:

Примеры:

! простой вывод сообщения.
msg 'Много спелых груш.'
! получим окно с сообщением 'Много спелых груш'

! Пример сообщения в действии ACT.
act 'Поесть груш':
   msg 'Ммм груши очень вкусные.'
end
! Получим вывод сообщения при клике по действию "Поесть груш"

!Пример с условием.
if hlebgotov = 1:
    msg 'Похоже хлеб уже готов.'
end
! Получаем вывод сообщения когда условие hlebgotov = 1

NL

NL — переход на новую строку, затем вывод текста в окне дополнительного описания. Общая запись:

NL [$текст]

, где [$текст] — любая строка текста, число, или выражение любого типа. Если [$текст] отсутствует, происходит просто переход на новую строку. Пример:

p "Текст без перехода на новую строку."
nl "Переход на новую строку + выведение текста."
p "Текст без перехода на новую строку."

OPENGAME

OPENGAME — загрузка указанного файла состояния игры. Общая запись:

OPENGAME [$путь]

, где [$путь] — путь к файлу сохранённого состояния игры. Если параметр [$путь] отсутствует, то вызывается окно загрузки состояния игры.

Пример:

! загрузка состояния из файла 1.sav
opengame "1.sav"
! открываем окно загрузки состояния
opengame

См. также локацию-обработчик события загрузки события загрузки состояния игры ($ongload).

OPENQST

OPENQST — открытие и запуск указанного файла игры. Общая запись:

OPENQST [$путь]

, где [$путь] — путь к файлу игры, который требуется запустить. Пример:

openqst "gamespool/cubesgame.qsp"

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

killall & cls & close all

P

P — вывод текста в окно дополнительного описания без перехода на новую строку. Вывод текста любым другим оператором сразу после p добавит новый текст сразу после текущего. Общая запись:

P [$текст]

, где [$текст] — любая строка текста, число, или выражение любого типа. [$текст] может быть пустой строкой '', но не должен отсутствовать. Пример:

p "Текст без перехода на новую строку."
p "Текст без перехода на новую строку."
p ""
p "Текст без перехода на новую строку."

PL

PL — вывод текста в окно дополнительного описания, затем переход на новую строку. Общая запись:

PL [$текст]

, где [$текст] — любая строка текста, число, или выражение любого типа. [$текст] может отсутствовать, тогда просто переход на новую строку. Пример:

pl "Вывод текста, затем переход на новую строку."
pl & ! переход на новую строку без вывода текста
pl "Вывод текста, затем переход на новую строку."
p "Текст без перехода на новую строку."
pl "Вывод текста, затем переход на новую строку."

PLAY

PLAY — проигрывание указанного звукового файла с заданной громкостью. Общая запись:

PLAY [$путь к звуковому файлу],[#громкость]

, где [$путь к звуковому файлу] — путь к звуковому файлу относительно файла игры, [#громкость] — громкость воспроизведения в процентах от 0 до 100. Параметр [#громкость] может отсутствовать, при этом громкость принимается равной 100%. Примеры:

!Громкость 100%
play 'sound/music.mp3'
!Громкость 50%
play 'sound/music.mp3', 50
!Громкость 0% (без звука)
play 'sound/music.mp3', 0

!Проигрывание файла по адресу из переменной $file
! с расширением 'mid'
! и громкостью volume
$file = "melody"
play '<<$file>>.mid', volume
! аналогично:
$file = "melody.mid"
play $file, volume

Если файл уже проигрывается, то изменяется громкость звучания без его "перезапуска". Поддерживается множество различных аудиоформатов и одновременное звучание до 32-х композиций.

REFINT

REFINT — принудительное обновление интерфейса (в т.ч. смена цветов, шрифтов, назначенных с помощью системных переменных).

По умолчанию обновление интерфейса происходит 2 раза в секунду (каждые 500 мс). Так же см. оператор settimer.

SAVEGAME

SAVEGAME — сохранение состояния игры в указанный файл. Общая запись:

SAVEGAME [$путь]

, где [$путь] — путь к создаваемому файлу сохранения состояния игры. Если параметр [$путь] отсутствует, то вызывается окно сохранения состояния игры.

Пример:

! сохранение состояния в файл 1.sav
savegame "1.sav"
! открываем окно сохранения состояния
savegame

См. также локацию-обработчик события сохранения состояния игры ($ongsave).

SCANSTR

SCANSTR — поиск в строке непересекающихся вхождений, соответствующих шаблону, и помещение этих вхождений в массив. Общая запись:

SCANSTR [$имя_массива], [$текст_для_разбора], [$регэксп], [#номер_группы]

, где [$имя_массива] — массив, в который помещаются строки, соответствующие регулярному выражению [$регэксп]. поиск производится по строке [$текст_для_разбора]. Если указан параметр [#номер_группы], в массив будет помещаться не вся строка, соответствующая регулярному выражению, а лишь часть, соответствующая указанной группе в этом регулярном выражении.

Примеры:

! вытаскиваем из строки все слова:
$text = 'Шла Саша по шоссе, а Грека через реку.'
scanstr '$words', $text, '\b\w+\b'
!В массиве $words окажутся значения: 'Шла', 'Саша', 'по', 'шоссе', 'а', 'Грека', 'через', 'реку'

! разбиваем строку по разделителю:
$text = 'утро|день|вечер|ночь'
scanstr '$words', $text, '[^|]+'
!В массиве $words окажутся значения: 'утро', 'день', 'вечер', 'ночь'

! вытаскиваем из строки все слова, помещённые в квадратные скобки, но без квадратных скобок:
$text = '[first] ignoredtext [second][third] also ignored'
scanstr '$words', $text, '\[(.*?)\]', 1
!В массиве $words окажутся значения: 'first', 'second', 'third'

SET

SET — оператор для установки значений переменных. Общая запись:

SET [название переменной] = [выражение]
SET [переменная 1], [переменная 2], ... = [значение 1], [значение 2], ...

, где [название переменной] — это допустимое имя переменной, [выражение] — это допустимое для данной переменной значение.

Названия числовых переменных записываются без символа $ в начале. Названия текстовых переменных записываются с символом $ в начале. Примеры:

! задаём текстовую переменную
set $text = "text string"
! задаём числовую переменную
set abs = 123
! задаём кортеж
set %tuple = [27, 184, 'steel']
! множественное присваивание
set unit_power, $unit_name = 1300, 'DiggerBull'
! распаковка кортежа
set $name, age, height = %npc_fields

Рекомендация:

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

set яблоки_в_кармане, яблоки_в_лукошке, яблоки_у_Лёшки = 58, 11, 19
set $строка_1, $строка_2 = 'Ехал Грека Через Реку', 'Видит Грека В Реке Рак'

SETTIMER

SETTIMER — задаёт интервал обращения к локации-счётчику. Общая запись:

SETTIMER [#выражение]

, где [#выражение] — период обращения к локации-счётчику в миллисекундах. По умолчанию плеер обращается к локации-счётчику каждые 500 мс., т.е. 2 раза в секунду.

Установка периода обращения к локации-счётчику влияет и на частоту автоматического обновления настроек интерфейса.

Примеры:

! локация-счётчик будет запускаться каждые 2 секунды:
settimer 2000

! локация-счётчик будет запускаться 4 раза в секунду:
settimer 250

! если мы задаём частоту обращения (раз в секунду)
frequency=10 & ! десять раз в секунду
settimer 1000/frequency

! если мы задаём период обращения (через сколько секунд)
period=2 & ! каждые две секунды
settimer 1000*period

Минимальное значение периода таким образом может быть 1 миллисекунда:

settimer 1

Однако на практике минимальное значение ограничено мощностью вашего компьютера, и оно, как правило, выше 1 миллисекунды.

SETVAR

SETVAR — присваивает значение переменной или ячейке массива.

Данная функция позволит избегать использования dynamic в тех случаях, когда нужно присвоить значение переменной, имя которой заранее неизвестно.

Общая запись:

SETVAR [$имя_массива], [значение], [индекс]

, где [$имя_массива] — название массива или переменной, которой нужно присвоить значение; [значение] — значение любого типа: строка, число, кортеж, — однако тип значения, которое будет помещено в переменную определяется по префиксу типа перед именем переменной; [индекс] — если значение присваивается ячейке массива, необходимо указать индекс ячейки данным параметром (может быть любого типа).

Примеры:

SETVAR 'A', 65
SETVAR '$X', 'name', 4
SETVAR '$X', 'name', 'string index'
SETVAR '%Q', ['пример', 'кортежа'], 3
SETVAR '%Q', ['пример', 'кортежа'], [x, y]

$arr_pref = '%'
$arr_name = 'tuple'
SETVAR $arr_pref+$arr_name, ['кортеж', 1], 3

SHOWACTS

SHOWACTS — управляет отображением окна действий на экране. Общая запись:

SHOWACTS [#выражение]

, где [#выражение] — это число. Обычно используются значения 0 и 1. Если значение выражения [#выражение] отлично от нуля, окно действий отображается. Если значение выражения [#выражение] равно нулю, окно действий скрыто. Примеры:

showacts 1 & ! показывает список действий
showacts 0 & ! скрывает список действий

Для удобства чтения кода можно заранее определить переменные on и off и использовать их:

on = 1
off = 0
showacts on & ! показывает список действий
showacts off & ! скрывает список действий

SHOWINPUT

SHOWINPUT — управляет отображением строки ввода на экране. Общая запись:

SHOWINPUT [#выражение]

, где [#выражение] — это число. Обычно используются значения 0 и 1. Если значение выражения [#выражение] отлично от нуля, строка ввода отображается. Если значение выражения [#выражение] равно нулю, строка ввода скрыта. Примеры:

showinput 1 & ! показывает строку ввода
showinput 0 & ! скрывает строку ввода

Для удобства чтения кода можно заранее определить переменные on и off и использовать их:

on = 1
off = 0
showinput on & ! показывает строку ввода
showinput off & ! скрывает строку ввода

SHOWOBJS

SHOWOBJS — управляет отображением инвентаря на экране. Общая запись:

SHOWOBJS [#выражение]

, где [#выражение] — это число. Обычно используются значения 0 и 1. Если значение выражения [#выражение] отлично от нуля, инвентарь отображается. Если значение выражения [#выражение] равно нулю, инвентарь скрыт. Примеры:

showobjs 1 & ! показывает инвентарь
showobjs 0 & ! скрывает инвентарь

Для удобства чтения кода можно заранее определить переменные on и off и использовать их:

on = 1
off = 0
showobjs on & ! показывает инвентарь
showobjs off & ! скрывает инвентарь

SHOWSTAT

SHOWSTAT — управляет отображением окна дополнительного описания на экране. Общая запись:

SHOWSTAT [#выражение]

, где [#выражение] — это число. Обычно используются значения 0 и 1. Если значение выражения [#выражение] отлично от нуля, окно дополнительного описания отображается. Если значение выражения [#выражение] равно нулю, окно дополнительного описания скрыто. Примеры:

showstat 1 & ! показывает окно дополнительного описания
showstat 0 & ! скрывает окно дополнительного описания

Для удобства чтения кода можно заранее определить переменные on и off и использовать их:

on = 1
off = 0
showstat on & ! показывает окно дополнительного описания
showstat off & ! скрывает окно дополнительного описания

SORTARR

SORTARR — сортировка указанного массива. Общая запись:

SORTARR [$имя_массива], [#порядок]

Здесь [$имя_массива] — название массива, который нужно отсортировать. Параметр [#порядок] можно не указывать. Если не указан или равен 0, то сортирует массив по возрастанию (от меньшего к большему). Если равен 1, то сортирует массив по убыванию (от большего к меньшему).

Может сортировать массивы любых типов (числа, строки, кортежи), но не допускается смешивать значения разных типов в одном массиве.

Для указания типа сортируемых значений нужно указать префикс типа как часть имени массива ($, %).

Пример сортировки текстового массива:

$a[] = 'nn'
$a[] = 'zz'
$a[] = 'aa'
sortarr '$a'

!проверяем результат сортировки:
loop local i=0 while i<arrsize('$a') step i+=1:
  *pl $a[i]
end

UNPACKARR

UNPACKARR — распаковка кортежа в указанный массив. Общая запись:

UNPACKARR [$имя_массива], [%кортеж], [#начальный_индекс], [#количество]

, где [$имя_массива] — массив, в который хотим поместить распакованные значения; [%кортеж] — кортеж, который хотим распаковать; [#начальный_индекс] — номер элемента в кортеже, начиная с которого мы хотим извлечь значения в массив; [#количество] — число элементов кортежа, которые мы хотим поместить в массив.

Индексация элементов в кортеже начинается с 0.

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

Примеры:

UNPACKARR 'A', ['тест','нескольких','значений',67, ['вложенный кортеж']]
! $A[0] будет содержать 'тест'
! $A[1] будет содержать 'нескольких'
! $A[2] будет содержать 'значений'
! A[3] будет содержать 67
! %A[4] будет содержать ['вложенный кортеж']

%tpl = ['тест','нескольких','значений',67, ['вложенный кортеж']]
UNPACKARR 'A', %tpl, 3, 1
! в A будет 67

UNSELECT

UNSELECT — отмена выделения предмета. Имеет краткую форму unsel.

При щелчке играющим по какому-либо предмету, он остаётся выделенным. Чтобы снять выделение с предмета используется данный оператор. Обычно его размещают на локации-обработчике выделения предмета.

if $selobj='Апельсин':
    *P 'Вкусный сладкий апельсин. Много нас, а он один.'
end
if $selobj = 'Чайник':
    p 'Самый обычный чугунный чайник.'
end
...
if $selobj='Отвёртка':
    menu '$screwdriver'
end
unsel

VIEW

VIEW — выводит на экран указанное изображение. В классическом плеере изображение выводится в отдельном окошке (окно предпросмотра), в qSpider изображение выводится в виде слоя. Общая запись:

VIEW [$путь к графическому файлу]

, где [$путь к графическому файлу] — путь к файлу картинки. Если параметр [$путь к графическому файлу] отсутствует, или задан как '' (пустая строка), окно предпросмотра закрывается.

Примеры:

! выводим изображение в окне предпросмотра
view 'content/monster.png'
! закрываем окно предпросмотра
view ''

! закрыть окно предпросмотра можно и так
view

WAIT

WAIT — приостановка выполнения кода программы на указанное количество миллисекунд. Общая запись:

WAIT [#миллисекунды]

, где [#миллисекунды] — время в миллисекундах, на какое следует остановить выполнение кода программы.

Пример:

! остановка выполнения программы на 5 секунд
wait 5000

Осторожно!

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

WAIT не только прерывает выполнение кода, но так же заставляет плеер выводить на экран информацию из буфера экрана. При нормальном выполнении кода локации, весь текст для операторов *pl, *p pl, nl и т.д. помещается в специальный буфер экрана, и уже после выполнения всего кода на локации выводится на экран. При использовании WAIT текст из буфера выводится сразу в момент выполнения WAIT, что иногда полезно, поскольку позволяет проследить изменение некоторых значений поэтапно.

В примере ниже числа сначала запишутся в буфер экрана и только потом появятся на экране:

loop i=0 while i<5 step i+=1:
    *p i
end
*pl

В следующем примере, они будут выводиться друг за другом с интервалом примерно в 100 мс.

loop i=0 while i<5 step i+=1:
    wait 100
    *p i
end
*pl

XGOTO

XGOTO — переход на указанную локацию без очистки окна основного описания. Общая запись:

XGOTO [$локация], [аргумент 0], [аргумент 1], ... , [аргумент 18]

, где [$локация] — название локации, на которую должен быть осуществлён переход. Аргументы [аргумент 0], [аргумент 1] и т.д. могут использоваться на этой локации, их значения автоматически помещаются в переменные args[0], args[1], и т.д. соответственно. Использование аргументов не обязательно.

При переходе на новую локацию при помощи xgoto не очищается окно основного описания, а базовое описание новой локации добавляется к уже имеющемуся тексту в окне основного описания. Список действий очищается, затем в окно действий выводятся базовые действия, а так же выполняется код из поля "Выполнить при посещении" локации [$локация]. Так же при переходе на новую локацию изменяется значение, возвращаемое функцией $curloc.

Примеры:

! переход на локацию "дом".
! Массив args на локации "дом" будет пуст.
xgoto 'дом'

! переход на локацию "улица" с передачей 2-х параметров.
! на локации "улица" args[0] равен 1,
! $args[1] содержит строку "данные".
xgoto 'улица', 1, 'данные'

Оператор имеет краткую форму xgt:

XGT [$локация], [аргумент 0], [аргумент 1], ... , [аргумент 18]