Системные переменные

$BACKIMAGE

$BACKIMAGE — содержит путь к файлу фонового изображения для окна основного описания. Фон в окне основного описания отображается в том случае, если значение данной переменной отлично от '' (т.е. не пустая строка) и файл изображения удалось загрузить.

Пример:

$backimage = "img/bg.png" & ! устанавливаем фоновым изображение, которое лежит в папке "img".

$backimage = "" & ! убираем изображение из фона окна основного описания.

$COUNTER

$COUNTER — содержит название локации-счётчика. Локация-счётчик может использоваться для реалтаймовых событий (то есть событий, происходящих в действительном времени); например, плавное изменение цвета фона, постепенный вывод текста на экран, плейлист для постоянного проигрывания музыки и другие.

Локация-счетчик вызывается через одинаковые промежутки времени, по умолчанию каждые 500 мс, т.е. 2 раза в секунду. Автоматическое обновление интерфейса срабатывает с той же частотой. Промежутки задаются оператором settimer в миллисекундах.

Если ваша локация-счётчик называется "Счётчик", на самой первой локации в игре нужно написать:

$counter = 'Счётчик'

Как правило, чтобы не путаться, локацию называют так же, как и служебную переменную — "Counter":

$counter = 'Counter'

Чтобы отключить выполнение локации-счётчика, нужно задать пустое значение переменной $COUNTER:

$counter = ""

< 5.7.0

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

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

$FNAME

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

Пример:

! устанавливаем для всей игры шрифт Courier New

$fname = "Courier New"

$ONACTSEL

$ONACTSEL — содержит название локации-обработчика события "выделение действия" (далее "обработчик выделения действия"). Иными словами, в этой переменной указывается название локации, код на которой срабатывает, когда одно из выведенных на экран действий выделено.

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

Назначаем в качестве обработчика выделения действия локацию "on_mouse":

$onactsel = "on_mouse"

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

if instr($selact, 'пойти', 1): play 'sounds\walk.mp3'

Чтобы отключить обработчик выделения действия, нужно задать переменной $onactsel пустое значение:

$onactsel = ""

$ONGLOAD

$ONGLOAD — содержит название локации-обработчика события "загрузка состояния игры" (далее "обработчик загрузки состояния"). Иными словами, в эту переменную записывается название локации, код которой будет выполняться всякий раз после того, как был загружен файл сохранения состояния игры ("файл сохранения") с помощью команды opengame.

Назначаем в качестве обработчика загрузки состояния локацию "on_game_load":

$ongload = "on_game_load"

Чтобы отключить обработчик загрузки состояния, нужно задать переменной $ongload пустое значение:

$ongload = ""

$ONGSAVE

$ONGSAVE - содержит название локации-обработчика события "сохранение состояния игры" (далее "обработчик сохранения состояния"). Иными словами, в эту переменную записывается название локации, код которой будет выполняться всякий раз перед тем, как будет записано состояние игры в новый или уже существующий файл сохранения состояния игры ("файл сохранения") с помощью команды savegame.

Назначаем в качестве обработчика сохранения состояния локацию "on_game_save":

$ongsave = "on_game_save"

Чтобы отключить обработчик сохранения состояния, нужно задать переменной $ongsave пустое значение:

$ongsave=""

$ONNEWLOC

$ONNEWLOC — содержит название локации-обработчика перехода на новую локацию (аналог локации "common" в URQ; далее "*обработчик перехода на новую локацию")). Иными словами, в эту переменную записывается название локации, код которой выполняется каждый раз после выполнения кода локации, на которую был осуществлён переход с помощью операторов goto или xgoto. Управление игрой передаётся игроку уже после выполнения кода на этой локации-обработчике.

Назначаем в качестве обработчика перехода на новую локацию локацию "on_goto_newloc":

$onnewloc = "on_goto_newloc"

Получить название локации, на которую был осуществлён переход, можно с помощью функции $curloc.

if $curloc = 'дом': кошка = 1

Чтобы отключить локацию-обработчик перехода на новую локацию, нужно задать переменной $onnewloc пустое значение:

$onnewloc = ""

$ONOBJADD

$ONOBJADD — содержит название локации-обработчика события "добавление предмета" (далее "*обработчик добавления предмета"). Иными словами, в эту переменную записывается название локации, код которой выполняется всякий раз после добавления предмета в окно предметов с помощью команды addobj.

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

• $ARGS[0] - название добавленного предмета
• $ARGS[1] - путь к картинке добавленного предмета

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

Назначаем в качестве обработчика добавления предмета локацию "on_object_add":

$onobjadd = "on_object_add"

Чтобы отключить обработчик добавления предмета, нужно задать переменной $onobjadd пустое значение:

$onobjadd = ""

$ONOBJDEL

$ONOBJDEL — содержит название локации-обработчика события "удаление предмета" (далее "*обработчик удаления предмета"). Иными словами, в эту переменную записывается название локации, код которой выполняется всякий раз при удалении предмета с помощью команды delobj. Если воспользоваться командой killobj, то это будет аналогично серии команд delobj, соответственно и локация-обработчик будет вызвана столько раз, сколько предметов будет удалено с помощью killobj.

При использовании команды killall локация-обработчик удаления предмета не вызывается, поскольку системная переменная $onobjdel уничтожается раньше удаления предметов.

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

• $ARGS[0] - название удалённого предмета

Назначаем в качестве обработчика удаления предмета локацию "on_object_del":

$onobjdel = "on_object_del"

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

! например есть предмет, который нам пригодится по сюжету

if $args[0] = "Важный артефакт":
    ! восстанавливаем предмет

    addobj $args[0]
end

Чтобы отключить обработчик удаления предмета, нужно задать переменной $onobjdel пустое значение:

$onobjdel = ""

$ONOBJSEL

$ONOBJSEL — содержит название локации-обработчика события "выделение предмета" (далее "обработчик выделения предмета"). Иными словами, в этой переменной указывается название локации, код на которой выполняется всякий раз при выделении предмета. Выделение предмета происходит непосредственно при "нажатии" на предмет (щелчок мышью по предмету).

Назначаем в качестве обработчика выделения предмета локацию "on_object_select":

$onobjsel = "on_object_select"

Данная локация полезна, к примеру, для вывода информации о предмете, или меню предмета. Получить название выбранного предмета можно через функцию $selobj.

if $selobj = 'чайник':
    p 'Cамый обычный чугунный чайник.'
end

При выборе играющим какого-либо предмета, он остаётся выделенным. Снять выделение можно командой unselect.

Чтобы отключить обработчик выделения предмета, нужно задать переменной $onobjsel пустое значение:

$onobjsel = ""

$USERCOM

$USERCOM — содержит название локации-обработчика строки ввода (поля ввода) (далее "*обработчик строки ввода"). Код данной локации-обработчика выполняется, если курсор установлен в строку ввода в момент нажатия клавиши "Enter" .

Назначаем в качестве обработчика строки ввода локацию "user_command_line":

$usercom = "user_command_line"

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

! если введённый текст соответствует названию существующей локации

if loc($user_text):
    ! осуществляем переход на эту локацию

    goto $user_text
end

Чтобы отключить обработчик строки ввода, нужно задать переменной $usercom пустое значение:

$usercom = ""

ARGS

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

Пример:

gosub "em.arr.sort", "$mass", "rug", "$time_ar"

Здесь на локацию "em.arr.sort" будут переданы три аргумента, которые будут помещены в первые три ячейки массива $args соответственно. То есть в момент начала выполнения кода на локации "em.arr.sort" в $args[0] уже будет присутствовать значение "$mass", в $args[1] — значение "rug", в $args[2] — значение "$time_ar".

При использовании операторов gosub, goto, xgoto, dynamic и функций dyneval, func можно указать до девятнадцати таких аргументов, и все они будут помещены в ячейки массива args с нулевой по восемнадцатую. Однако, поскольку args — это всё же массив, вы можете работать с ним, как с обычным массивом, т.е. использовать больше девятнадцати ячеек, назначать текстовые индексы и т.д.

Отличительной особенностью массива args является то, что для каждого отдельного блока кода создаётся свой собственный массив args. То есть если вы из локации "1" вызываете локацию "2", то на локации "1" действует собственный массив args, а на локации "2" — собственный, и значения в этих массивах не пересекаются.

Пример:

# локация_1
args[0]=23
gosub "локация_2", 34
*pl args[0]
-

# локация_2
*pl args[0]
-

Запустив этот код, вы увидите, что сначала будет выведено число 34, и только затем 23.

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

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

• код локаций
• код, передаваемый dynamic/dyneval
• код в гиперссылках
• код в циклах
• код действий

В первых трёх случаях для каждой отдельной сессии таких блоков кода плеер будет создавать собственный массив args.

Однако:

• в циклах будет использоваться массив args, созданный в блоке кода, из которого цикл был вызван.
• в действиях будет использоваться массив args, созданный на локации, на которую был осуществлён переход с помощью операторов goto или xgoto.

BCOLOR

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

! чёрный цвет фона

bcolor = -16777216
! красный цвет фона

bcolor = -16776961
! белый цвет фона

bcolor = -1

Поскольку цвет фона кодируется специальным числом, а вычислять это число самостоятельно неудобно, следует пользоваться функцией rgb, которой в качестве аргументов передаются три составляющие цвета:

! задаём цвет фона через функцию rgb(red,green,blue)

! фон синего цвета

bcolor = rgb(0, 0, 255)
! фон жёлтого цвета

bcolor = rgb(255, 255, 0)
! фон оранжевого цвета

bcolor = rgb(255, 130, 0)
! фон голубого цвета

bcolor = rgb(0, 255, 255)
! фон малинового цвета

bcolor = rgb(255, 0, 255)

DEBUG

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

Совет:

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

DISABLESCROLL

DISABLESCROLL — если значение переменной отлично от нуля, автопрокрутка текста в окнах основного и дополнительного описаний отключается.

Что это значит

Предположим, мы вывели на экран большой объём текста, а затем при нажатии на действие у нас выводится ещё один фрагментик текста. Если DISABLESCROLL = 0, этот фрагментик текста при выводе заставит экран прокрутиться вниз. Если мы не хотим, чтобы экран прокручивался вниз в этом случае, мы присваиваем переменной DISABLESCROLL единицу.

Довольно мутное поведение в классическом плеере — при некоторых обстоятельствах текст и так не прокручивается.

Примечание от Байта:

По идее disablescroll используется при обновлении окна. если в момент обновления там значение 0 и при этом не было перехода на новую локацию (GT/XGT), то описание скроллируется до конца текста

Обновление окна происходит в разных случаях - например, после того, как игрок совершил какое-то действие (выбрал действие / предмет), или игра вызвала refint или какое-либо модальное окно (``input/msg/menu` - то, что я могу сходу вспомнить)

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

DISABLESUBEX

Будьте внимательны!

В плеерах версии 5.8.0 и выше эта переменная больше не используется.

DISABLESUBEX — если значение переменной отлично от нуля, отключается вычисление подвыражений в строках. Пример:

var = 123
$text = '<<var>>'    & ! переменной $text будет присвоена строка '123'
*pl 'string <<var>>'    & ! на экран будет выведена строка 'string 123'
*pl '<<5+6>>'        & ! на экран будет выведена строка '11'

disablesubex = 1    & ! отключаем вычисление подвыражений

$text = '<<var>>'    & ! переменной $text будет присвоена строка '<<var>>'
*pl 'string <<var>>'    & ! на экран будет выведена строка 'string <<var>>'
*pl '<<5+6>>'        & ! на экран будет выведена строка '<<5+6>>'

FCOLOR

FCOLOR — содержит цвет используемого в данный момент шрифта. Если равна 0, то используется цвет, заданный в настройках программы. Изменение значения переменной меняет цвет всего текста игры, кроме гиперссылок и текста, цвет которого переназначен через HTML. Пример:

! чёрный цвет текста

fcolor = -16777216
! красный цвет текста

fcolor = -16776961
! белый цвет текста

fcolor = -1

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

! задаём цвет текста через функцию rgb(red,green,blue)

! текст чёрного цвета

fcolor = rgb(0, 0, 0)
! текст белого цвета

fcolor = rgb(255, 255, 255)
! текст красного цвета

fcolor = rgb(255, 0, 0)
! текст зелёного цвета

fcolor = rgb(0, 255, 0)

FSIZE

FSIZE — содержит размер используемого в данный момент шрифта. Если равна 0, то используется размер, заданный в настройках программы. Относительно данного значения в HTML-режиме вычисляются размеры шрифтов тега <font>. Пример:

fsize = 18

Размер шрифта устанавливается для всего текста в игре, кроме текста, размер которого переназначен через HTML.

LCOLOR

LCOLOR — содержит текущий цвет шрифта гиперссылок. Если равна 0, то используется цвет, заданный в настройках программы. Изменение значения переменной меняет цвет текста всех гиперссылок, кроме тех, цвет которых переназначен через HTML. Пример:

! чёрный цвет гиперссылок

lcolor = -16777216
! красный цвет гиперссылок

lcolor = -16776961
! белый цвет гиперссылок

lcolor = -1

Поскольку цвет в QSP кодируется специальным числом, а вычислять это число самостоятельно неудобно, следует пользоваться функцией rgb, которой в качестве аргументов передаются три составляющие цвета:

! задаём цвет  гиперссылок через функцию rgb(red,green,blue)

!  гиперссылки синего цвета

lcolor = rgb(0, 0, 255)
! гиперссылки жёлтого цвета

lcolor = rgb(255, 255, 0)
! гиперссылки оранжевого цвета

lcolor = rgb(255, 130, 0)
! гиперссылки голубого цвета

lcolor = rgb(0, 255, 255)
! гиперссылки малинового цвета

lcolor = rgb(255, 0, 255)

NOSAVE

NOSAVE — если значение данной переменной отлично от 0, пункт меню плеера "Сохранить состояние игры" игроку становится недоступен, т.е. игрок не может самостоятельно сохранить игру. В то же время на уровне кода QSP продолжает работать оператор savegame. Пример:

! отключаем возможность сохранения игры

nosave = 1
act "Бросить кости":
    cubes = rand(1, 6)
    ! включаем возможность сохранений обратно

    nosave = 0
    delact $selact
end

RESULT

RESULT — специфическая системная переменная, предназначенная для получения значения в текущем блоке кода и передачи этого значения функции func или dyneval. Иными словами, чтобы функции func или dyneval вернули какое-то значение, необходимо в вызываемом ими блоке кода присвоить значение переменной result.

Например:

$dyneval {
  if args[0] mod 2 = 0:
    $result = 'чётное число'
  else
    $result = 'нечётное число'
  end
}, 279

Для каждого отдельного блока кода плеером создаётся собственная переменная result. То есть если вы из локации "1" вызываете локацию "2", то на локации "1" создаётся собственная переменная result, а на локации "2" — собственная, и значения в этих переменных не пересекаются. Таким образом переменная result является локальной для каждого отдельного вызова блока кода.

Если при обработке блока кода были установлены и result, и $result, и %result то в результат вернётся значение, записанное в переменную последним.

примечание

В плеерах версии 5.7.0. может наблюдаться небольшая проблема с пересечением значений в result на разных локациях. Использовать переменную result рекомендуется только в конце кода локации.

В более новых версиях плееров эту проблему исправили и result можно использовать наравне с args.

USEHTML

USEHTML — если значение данной переменной отлично от нуля, включается режим распознавания HTML. При этом HTML разметку можно использовать в названиях действий, предметов, в тексте, выводимом в окна основного и дополнительного описаний, а так же в диалоговых окнах, вызываемых оператором msg и функцией $input.

! включение HTML

usehtml = 1
! вывод текста с HTML-разметкой

*pl "<font color=#ff8888>Красный текст.</font>"

qSpider

В qSpider распознавание включено всегда и не отключается изменением значения переменной usehtml.

Примечания для любопытных

1. Есть возможность определить любую системную переменную локальной для отдельного блока кода, и тогда эту системную переменную можно использовать как обычную локальную переменную, т.е. она не повлияет на работу плеера. Однако, строго не рекомендуется так делать, чтобы не допускать возможных ошибок.
2. Как и все прочие переменные в QSP, системные переменные так же являются массивами.

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

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

     $counter[] = 'playlist'
     $counter[] = 'animation'
     $counter[] = 'time.acts'

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

     ! будут выполняться только локации 'playlist' и 'animation'
     $counter[] = 'playlist'
     $counter[] = 'animation'
     $counter[] = ''
     $counter[] = 'time.acts'