Различия

Здесь показаны различия между двумя версиями данной страницы.

--- help:service_locations [2013/11/05 19:34]
newsash
+++ help:service_locations [2024/11/09 03:20] (текущий)
byte [Служебные локации]
@@ Строка 1: / Строка 1: @@
-[[help:principle|Назад: Порядок работы интерпретатора]]
+[[help:jump|Назад: Переходы внутри локации]]
-=====Служебные локации=====
-В QSP есть возможность сделать так, что бы локация выполнялась каждый раз при возникновении определенного события. Для этого нужно присвоить название локации предназначенной для этого системной переменной. Выполнение локации происходит также, как при использовании оператора [[help:organizing|GS]]. Пример: <sxh qsp>
+====== Служебные локации ======
-$onobjsel = '$onobjsel'
-$onnewloc = '$перерисовка'
+В **QSP** существует возможность привязать вызов некоторых локаций к определённым событиям. Например, к выделению предмета в окне предметов, или к переходу на новую локацию с помощью операторов ''%%GOTO%%''/''%%XGOTO%%''.
-$onobjadd = '' &! Убрали обработчик
+Чтобы привязать вызов локации к определённому событию, нужно прописать название этой локации в ту или иную системную переменную, предназначенную для связки события с локацией.
+<sxh qsp>
+! назначили обработчик выделения предмета:
+$onobjsel = 'ONOBJSEL'
+! назначили обработчик перехода на новую локацию:
+$onnewloc = 'перерисовка'
+! сняли обработчик добавления предмета:
+$onobjadd = ''
 </sxh>
-  * Сохранения:
-    * **$ONGLOAD** - сразу после загрузки состоянии игры
+**Примечание:** При использовании операторов "''%%KILLALL%%'', ''%%KILLVAR%%''" очищаются также все системные переменные. В том числе и переменные, через которые назначаются локации-обработчики.
-    * **$ONGSAVE** - непосредственно перед сохранением состояния игры
-  * Предметы:
+Когда событие происходит, указанная локация вызывается точно так же, как если бы мы вызывали её с помощью оператора ''**[[help:organizing|GOSUB]]**'', с тем исключением, что на всех служебных локациях восстанавливаются глобальные переменные. Пример:
-    * **$ONOBJADD** - при добавлении предмета
-      * $ARGS[0] - название добавленного предмета
+<sxh qsp>
-      * $ARGS[1] - путь к картинке добавленного предмета
+# start
-    * **$ONOBJDEL** - при удалении предмета
+$ongsave = 'ogs'
-      * $ARGS[0] - название удалённого предмета
+i = 99
-    * **$ONOBJSEL** - при выборе предмета
-      * Получить название выбранного предмета можно через функцию "SELOBJ". <sxh qsp>
+act 'Save Game':
+    local i = 17
+    ! на экран будет выведено значение 99
+    savegame '1.sav'
+end
+act 'Print i':
+    local i = 137
+    ! на экран будет выведено 137
+    gosub 'ogs'
+end
+--
+# ogs
+*pl i
+--
+</sxh>
+В этом примере при сохранении игры на экран будет выведено число 99 из глобальной переменной ''%%i%%''. Если же локация ''%%ogs%%'' вызывается не как служебная, на неё транслируются значения локальной переменной ''%%i%%'', объявленной в действии.
+===== События в QSP =====
+В этом разделе перечислены все события в **QSP**, к которым можно привязать автоматический вызов локаций.
+==== Загрузка состояния игры ====
+''%%$ONGLOAD%%'' — содержит название локации-обработчика события "загрузка состояния игры" (далее "обработчик загрузки состояния"). Иными словами, в эту переменную записывается название локации, код которой будет выполняться всякий раз после того, как был загружен файл состояния игры ("файл сохранения") с помощью команды ''%%OPENGAME%%''. Название локации может быть любым.
+Назначаем в качестве обработчика загрузки состояния локацию "''%%on_game_load%%''":
+<sxh qsp>
+$ongload="on_game_load"
+</sxh>
+Теперь сразу после выполнения команды ''%%OPENGAME%%'' плеер будет автоматически вызывать локацию "''%%on_game_load%%''".
+Чтобы отключить обработчик загрузки состояния, нужно задать переменной ''%%$ONGLOAD%%'' пустое значение:
+<sxh qsp>
+$ongload=""
+</sxh>
+==== Сохранение состояния игры ====
+''%%$ONGSAVE%%'' - содержит название локации-обработчика события "сохранение состояния игры" (далее "обработчик сохранения состояния"). Иными словами, в эту переменную записывается название локации, код которой будет выполняться всякий раз перед тем, как записать состояние игры в новый, или уже существующий, файл состояния игры ("файл сохранения") с помощью команды ''%%SAVEGAME%%''. Название локации может быть любым.
+Назначаем в качестве обработчика сохранения состояния локацию "''%%on_game_save%%''":
+<sxh qsp>
+$ongsave="on_game_save"
+</sxh>
+Теперь сразу после выполнения команды ''%%SAVEGAME%%'' плеер будет автоматически вызывать локацию "''%%on_game_save%%''".
+Чтобы отключить обработчик сохранения состояния, нужно задать переменной ''%%$ONGSAVE%%'' пустое значение:
+<sxh qsp>
+$ongsave=""
+</sxh>
+==== Добавление предмета в окно предметов ====
+''%%$ONOBJADD%%'' — содержит название локации-обработчика события "добавление предмета в окно предметов" (далее "обработчик добавления предмета"). Иными словами, в эту переменную записывается название локации, код которой выполняется всякий раз после добавления предмета в окно предметов с помощью команды ''%%ADDOBJ%%''. Название локации может быть любым.
+При добавлении предмета этой локации-обработчику передаются два аргумента, значения которых можно получить из ''%%$ARGS[0]%%'' и ''%%$ARGS[1]%%'' соответственно:
+  * ''%%$ARGS[0]%%'' - название добавленного предмета
+  * ''%%$ARGS[1]%%'' - путь к картинке добавленного предмета
+Данная локация полезна, к примеру, для ограничения вместительности рюкзака.
+Назначаем в качестве обработчика добавления предмета локацию "''%%on_object_add%%''":
+<sxh qsp>
+$onobjadd="on_object_add"
+</sxh>
+Теперь сразу после выполнения команды ''%%ADDOBJ%%'' плеер будет автоматически вызывать локацию "''%%on_object_add%%''".
+Чтобы отключить обработчик добавления предмета, нужно задать переменной ''%%$ONOBJADD%%'' пустое значение:
+<sxh qsp>
+$onobjadd=""
+</sxh>
+==== Удаление предмета из окна предметов ====
+''%%$ONOBJDEL%%'' — содержит название локации-обработчика события "удаление предмета" (далее "обработчик удаления предмета"). Иными словами, в эту переменную записывается название локации, код которой выполняется всякий раз после удаления предмета с помощью команды ''%%DELOBJ%%''. Если воспользоваться командой ''%%KILLOBJ%%'', то это будет аналогично серии команд ''%%DELOBJ%%'', соответственно и локация-обработчик будет вызвана столько раз, сколько предметов будет удалено с помощью ''%%KILLOBJ%%''. Название локации может быть любым.
+При использовании команды ''%%KILLALL%%'' локация-обработчик удаления предмета не вызывается, поскольку системная переменная ''%%$ONOBJDEL%%'' уничтожается раньше удаления предметов.
+При удалении предмета обработчику удаления предмета передаётся аргумент, значение которого можно получить из ''%%$ARGS[0]%%'':
+  * ''%%$ARGS[0]%%'' - название удалённого предмета
+Назначаем в качестве обработчика удаления предмета локацию "''%%on_object_del%%''":
+<sxh qsp>
+$onobjdel="on_object_del"
+</sxh>
+Теперь сразу после выполнения команды ''%%DELOBJ%%'' плеер будет автоматически вызывать локацию "''%%on_object_del%%''". А сразу после выполнения команды ''%%KILLOBJ%%'' локация "''%%on_object_del%%''" будет вызвана столько раз, сколько предметов удалено этой командой.
+Данная локация полезна, к примеру, для проверки возможности удаления предмета:
+<sxh qsp>
+! например есть предмет, который нам пригодится по сюжету
+if $args[0]="Важный артефакт":
+    ! восстанавливаем предмет
+    addobj $args[0]
+end
+</sxh>
+Чтобы отключить обработчик удаления предмета, нужно задать переменной ''%%$ONOBJDEL%%'' пустое значение:
+<sxh qsp>
+$onobjdel=""
+</sxh>
+==== Выделение предмета в окне предметов ====
+''%%$ONOBJSEL%%'' — содержит название локации-обработчика события "выделение предмета" (далее "обработчик выделения предмета"). Иными словами, в этой переменной указывается название локации, код на которой выполняется всякий раз при выделении предмета. Выделение предмета происходит непосредственно при "нажатии" на предмет (щелчок мышью по предмету). Название локации может быть любым.
+Назначаем в качестве обработчика выделения предмета локацию "''%%on_object_select%%''":
+<sxh qsp>
+$onobjsel="on_object_select"
+</sxh>
+Теперь всякий раз после щелчка мышью на предмете будет выполняться код локации "''%%on_object_select%%''".
+Данная локация полезна, к примеру, для вывода информации о предмете, или для вызова меню предмета. Получить название выбранного предмета можно через функцию ''%%$SELOBJ%%''.
+<sxh qsp>
 if $selobj = 'чайник':
-  P 'Самый обычный чугунный чайник.'
+    p 'Cамый обычный чугунный чайник.'
 end
 </sxh>
-      * При выборе играющим какого-либо предмета, он остаётся выделенным. Снять выделение можно командой UNSELECT или UNSEL. <sxh qsp>
-if selobj = 'нож':
+При выборе играющим какого-либо предмета, он остаётся выделенным. Повторно выделить уже выделенный предмет нельзя. Снять выделение можно командой ''%%UNSELECT%%''.
-  *P 'Нельзя убить этого человека'
-  unsel
+<sxh qsp>
+if $selobj = 'нож':
+    *p 'Этим ножом даже хлеба не нарежешь.'
 end
+unselect &! или UNSEL
 </sxh>
-  * Локации:
-    * **$ONNEWLOC** - при переходе на новую локацию
+==== Переход на новую локацию ====
-      * Выполняется перед передачей управления игроку (после выполнения кода всех участвующих в переходах локаций)
-      * Получить название локации, на которую был осуществлён переход, можно с помощью функции "CURLOC"<sxh qsp>
+''%%$ONNEWLOC%%'' — содержит название локации-обработчика перехода на новую локацию (далее "обработчик перехода"). Иными словами, в эту переменную записывается название локации, код которой выполняется каждый раз после выполнения кода локации, на которую был осуществлён переход с помощью операторов ''%%GOTO%%'' или ''%%XGOTO%%''. Управление игрой передаётся игроку уже после выполнения кода на этой локации-обработчике. Название локации может быть любым.
+Назначаем в качестве обработчика перехода локацию "''%%on_goto_newloc%%''":
+<sxh qsp>
+$onnewloc="on_goto_newloc"
+</sxh>
+Теперь всякий раз после выполнения кода локации, на которую был осуществлён переход с помощью операторов ''%%GOTO%%'' или ''%%XGOTO%%'', будет автоматически вызываться локация "''%%on_goto_newloc%%''".
+Получить название локации, на которую был осуществлён переход, можно с помощью функции ''%%$CURLOC%%''.
+<sxh qsp>
 if $curloc = 'дом': кошка = 1
 </sxh>
-  * Действия:
-    * **$ONACTSEL** - при выборе действия.
+Чтобы отключить обработчик перехода, нужно задать переменной ''%%$ONNEWLOC%%'' пустое значение:
-      * Именно при выборе действия, а не при нажатии действия.
-      * Получить название выбранного действия можно через функцию"SELACT".<sxh qsp>
+<sxh qsp>
-if instr(1,$selact,'Пойти'): play 'sounds\walk.mp3'
+$onnewloc=""
 </sxh>
-  * Время
-    * **$COUNTER** - локация-счетчик вызывается через одинаковые промежутки времени
+==== Выделение действия ====
-      * По умолчанию промежутки 500мс, т.е. 2 раза в секунду
-      * Автоматическое обновление интерфейса срабатывает с той же частотой
+''%%$ONACTSEL%%'' — содержит название локации-обработчика события "выделение действия" (обработчик выделения действий). Иными словами, в этой переменной указывается название локации, код на которой срабатывает, когда одно из выведенных на экран действий выделяется. Название локации может быть любым.
-      * Промежутки задаются командой **SETTIMER** //[#период]// в миллисекундах <sxh qsp>
-SETTIMER 1000/частота_в_секундах
+Следует помнить, что выделение действия происходит при наведении на него указателя мыши, а не при непосредственном нажатии.
+Действие нельзя выделить повторно, если оно уже выделено.
+Важно! При управлении действиями с цифровой клавиатуры, выделение действий может "прыгать", из-за чего работа обработчика выделения действий может быть некорректна.
+Назначаем в качестве обработчика выделения действий локацию "''%%on_mouse%%''":
+<sxh qsp>
+$onactsel="on_mouse"
 </sxh>
-  * Строка ввода
-    * **$USERCOM** - по нажатию "Enter" в строке ввода
+Теперь всякий раз при наведении указателя мыши на любое из действий в окне действий, будет вызываться локация "''%%on_mouse%%''".
-      * Текущий текст строки ввода возвращает функция "USER_TEXT"
-      * Очистить строку ввода можно в любом месте игры с помощью оператора "CMDCLEAR".<sxh qsp>
+Данная локация полезна, к примеру, для вывода изображений или проигрывания звуков при выборе действий. Получить название выбранного действия можно через функцию ''%%$SELACT%%''.
-$text = $USER_TEXT
-CMDCLEAR
+<sxh qsp>
+if instr(1,$selact,'пойти'): play 'sounds\walk.mp3'
 </sxh>
-**Примечание:** При использовании операторов "KILLALL, KILLVAR" очищаются также все системные переменные.
+Чтобы отключить обработчик выделения действий, нужно задать переменной ''%%$ONACTSEL%%'' пустое значение:
+<sxh qsp>
+$onactsel=""
+</sxh>
+==== Ввод в строке ввода ====
+''%%$USERCOM%%'' — содержит название локации-обработчика строки ввода (поля ввода) (далее "обработчик ввода"). Код данной локации-обработчика выполняется, если курсор установлен в строку ввода в момент нажатия клавиши "Enter". Название локации может быть любым.
+Назначаем в качестве локации-обработчика строки ввода локацию "''%%user_command_line%%''":
+<sxh qsp>
+$usercom="user_command_line"
+</sxh>
+Теперь, если игрок установит курсор в строку ввода и начнёт нажимать клавишу "Enter", всякий раз при нажатии клавиши "Enter" будет вызываться локация "''%%user_comand_line%%''".
+Полезна при организации парсера (управление игрой с помощью строки ввода), или для организации отладчика. Получить текст, введённый игроком в поле ввода, можно с помощью функции ''%%$USER_TEXT%%''.
+Пример кода для локации-обработчика:
+<sxh qsp>
+! если введённый текст соответствует названию существующей локации
+if (loc $user_text)=-1:
+    ! осуществляем переход на эту локацию
+    goto $user_text
+elseif instr($user_text,'>')=1:
+    ! если первый символ в строке ввода это ">" ,
+    ! выполняем введённый в строку текст, как код
+    dynamic $mid($user_text,2)
+end
+</sxh>
+Чтобы отключить обработчик ввода, нужно задать переменной ''%%$USERCOM%%'' пустое значение:
+<sxh qsp>
+$usercom=""
+</sxh>
+Так же см. статью [[help:inputs|"Ввод текста игроком"]].
+===== Локация-счётчик =====
+Локация-счётчик не является обработчиком какого-то события, как такового. Она вызывается через примерно равные промежутки времени, поэтому здесь мы выделяем её в отдельную группу. Тем не менее, всё, что справедливо для локаций-обработчиков событий, справедливо и для локации-счётчика.
+''%%$COUNTER%%'' — содержит название локации-счётчика. Локация-счётчик может использоваться для реалтаймовых событий (то есть событий, происходящих в действительном времени); например, плавное изменение цвета фона, постепенный вывод текста на экран, плейлист для постоянного проигрывания музыки и другие. Название локации может быть любым.
+Как правило, чтобы не путаться, локацию называют так же, как и служебную переменную — "Counter":
+<sxh qsp>
+$counter='Counter'
+</sxh>
+Чтобы отключить выполнение локации-счётчика, нужно задать пустое значение переменной ''%%$COUNTER%%'':
+<sxh qsp>
+$counter=""
+</sxh>
+==== SETTIMER ====
+Локация-счетчик вызывается через одинаковые промежутки времени, по умолчанию каждые 500 мс, т.е. 2 раза в секунду. Автоматическое обновление интерфейса срабатывает с той же частотой. Промежутки задаются оператором ''%%SETTIMER%%'' в миллисекундах.
+**Внимание!!!** Период, выставляемый через ''%%SETTIMER%%'' — это очень условная величина. Он показывает только примерное время, когда локация-счётчик будет добавлена на выполнение в очередь. Непосредственно выполниться локация-счётчик может чуть позже, а то и сильно позже. Будьте бдительны.
+Если ваша локация-счётчик называется "''%%on_time%%''", на самой первой локации в игре нужно написать:
+<sxh qsp>
+$counter='on_time'
+</sxh>
+Теперь, если вы не использовали оператор ''%%SETTIMER%%'', примерно каждые 500 миллисекунд будет вызываться локация "''%%on_time%%''".
+Примеры выставления таймера:
+<sxh qsp>
+SETTIMER 1000/частота_в_герцах
+</sxh>
+<sxh qsp>
+SETTIMER 1000*период_в_секундах
+</sxh>
+Так же см. статью [[help:realtime|"Реальное время"]].
+===== Несколько обработчиков на одно событие =====
+Иногда возникает необходимость разгрузить локации-обработчики от большого объёма кода, или разнести логически не связанные фрагменты кода по разным локациям, но привязать код этих локаций к одному событию.
+Эта задача решается двумя способами.
+  * Назначаем в качестве локации-обработчика какого-либо события одну локацию, а уже из неё с помощью ''%%GOSUB%%'' вызываем необходимые локации, на которых мы разместили фрагменты кода: <sxh qsp>
+     ! самая первая локация в игре     $counter='counter'
+</sxh><sxh qsp>
+! локация counter
+gosub 'playlist'
+gosub 'rabbit_hole','animation'
+</sxh>
+  * Используем системную переменную, в которую обычно прописываем название локации-обработчика, как массив, и прописываем локации, на которых мы разместили фрагменты кода, в ячейки этого массива: <sxh qsp>
+     $counter[0]='playlist'     $counter[1]='rabbit_hole'
+</sxh> В данном случае плеер будет последовательно одну за другой вызывать локации, прописанные в этом массиве, пока массив не кончится, или пока плеер не встретит пустую ячейку (пустую строку в ячейке).
+Обратите внимание на преимущества и недостатки каждого способа.
+Первый способ позволяет вызывать сторонние локации из локации-обработчика, передавая на эти локации различные аргументы. Иногда это бывает очень удобно. Однако этот способ не даёт гибкости в управлении фрагментами кода. Вы не можете отключить вызов одной из сторонних локаций.
+Второй способ, напротив, делает все перечисленные в массиве локации локациями-обработчиками, и чтобы отключить обработку одной из этих локаций, достаточно удалить соответствующую ячейку. Однако, он не позволяет передавать на локации-обработчики необходимые аргументы.
-----
 [[help:dynamical|Вперёд: Динамический код]]

Документация QSPСайтФорум

Инструменты пользователя

Инструменты сайта

Различия

Инструменты страницы

Документация QSP
Сайт Форум