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

Эта страница только для чтения. Вы можете посмотреть исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
[[help:conditional|Назад: Условия]]

====== Пользовательские функции и процедуры ======

===== Общая информация о GOSUB и FUNC =====

Сам принцип написания игр на **QSP** предполагает, что игра будет состоять из отдельных блоков кода — локаций. Эти локации могут быть связаны между собой переходами с помощью операторов ''%%GOTO%%'' и ''%%XGOTO%%''. Таким образом в **QSP** реализуется перемещение по игре, например, перемещение с места на место, или по главам интерактивной истории.

Однако иногда нам необходимо использовать локации не как локации мест, не как главы или страницы, а для того, чтобы иметь возможность выполнять повторяющиеся фрагменты кода. Например, мы пишем на нескольких разных локациях действие подъёма яблок. И нам нужно, чтобы это действие увеличивало число яблок у нас в рюкзаке, уменьшало на соответствующей локации и добавляло предмет "Яблоки", если мы не поднимали ещё ни одного яблока.

В принципе мы это можем сделать, просто копируя на каждую локацию вот такое действие:

<sxh qsp>
act "Взять яблоко":
  if яблоки['рюкзак']=0:
    addobj "Яблоки"
  end
  яблоки['рюкзак'] += 1
  яблоки[$curloc] -= 1
end
</sxh>

Но посмотрите, сколько строчек кода это действие занимает. Семь. Если мы скопируем такое действие два или три раза, это ещё ничего, но что, если нам придётся копировать действие сто раз? Это семь сотен строчек кода. Это попросту увеличивает объём нашей игры в десятки раз. А ведь у нас может быть не одно такое действие.

Чтобы нам не приходилось писать одинаковый код множество и множество раз, в **QSP** предусмотрены специальный оператор ''%%GOSUB%%'' и специальная функция ''%%FUNC%%'', которые позволяют нам превращать любые локации в собственные процедуры и функции. В данном случае мы можем вынести код действия в отдельную локацию, назвать эту локацию ''%%"поднять_яблоко"%%'', а затем вызывать эту локацию из действия с помощью ''%%GOSUB%%''.

Локация ''%%"поднять_яблоко"%%'':

<sxh qsp>
!# поднять_яблоко
if яблоки['рюкзак']=0:
  addobj "Яблоки"
end
яблоки['рюкзак']+=1
яблоки[$curloc]-=1
</sxh>

Действие, которое мы пишем на любой другой локации:

<sxh qsp>
act "Взять яблоко":
  gosub "поднять_яблоко"
end
</sxh>

Как видите, всё наше действие сократилось до трёх строчек кода, а сам код подъёма яблока написан нами всего один раз!

(Подробнее о том, как работает оператор ''%%GOSUB%%'' вы можете прочитать в разделе ниже).

Ну а если, предположим, нам нужно написать сразу три действия по подъёму яблок? И все три эти действия отличаются только числом яблок, которые мы поднимаем:

<sxh qsp>
act "Взять одно яблоко":
  if яблоки['рюкзак']=0:
    addobj "Яблоки"
  end
  яблоки['рюкзак']+=1
  яблоки[$curloc]-=1
end
act "Взять два яблока":
  if яблоки['рюкзак']=0:
    addobj "Яблоки"
  end
  яблоки['рюкзак']+=2
  яблоки[$curloc]-=2
end
act "Взять пять яблок":
  if яблоки['рюкзак']=0:
    addobj "Яблоки"
  end
  яблоки['рюкзак']+=5
  яблоки[$curloc]-=5
end
</sxh>

Вроде бы код здесь тоже повторяется, но не совсем. Что же делать?

И для таких ситуаций в **QSP** уже предусмотрен специальный механизм. Дело в том, что оператор ''%%GOSUB%%'' позволяет передавать на локацию, которую мы с его помощью вызываем, различные значения. В данном случае нам нужно передавать на локацию ''%%"поднять_яблоко"%%'', которую мы писали в предыдущем примере, число яблок. В действиях это будет выглядеть вот так:

<sxh qsp>
act "Взять одно яблоко":
  gosub "поднять_яблоко",1
end
act "Взять два яблока":
  gosub "поднять_яблоко",2
end
act "Взять пять яблок":
  gosub "поднять_яблоко",5
end
</sxh>

Через запятую после названия локации мы можем перечислять различные значения (строковые, числовые, кортежи), и эти значения будут переданы на указанную локацию. Однако где на локации ''%%"поднять_яблоко"%%'' нам искать эти переданные значения?

Всё просто. Значения, которые мы передаём на локацию таким образом, автоматически помещаются в массив ''%%ARGS%%'', в ячейки, начиная с нулевой. И получается, что нам надо искать наше значение в ''%%ARGS[0]%%'':

<sxh qsp>
!# поднять_яблоко
if яблоки['рюкзак'] = 0:
  addobj "Яблоки"
end
яблоки['рюкзак'] += args[0]
яблоки[$curloc] -= args[0]
</sxh>

Можно передавать до девятнадцати любых значений на локацию и искать их на этой локации в массиве ''%%ARGS%%'' соответственно в ячейках с нулевой по восемнадцатую. Вот ещё пример передачи аргументов:

Локация ''%%"Приготовить"%%'':

<sxh qsp>
!# приготовить
*pl "Я должен приготовить <<$args[0]>>, но не просто <<$args[0]>>, а <<$args[0]>> <<$args[1]>>, чтобы съесть <<$args[2]>>."
</sxh>

А вот пример вызова этой локации из действий:

<sxh qsp>
act "Завтрак":
  gosub "Приготовить","яичницу","с луком","на завтрак"
end
act "Обед":
  gosub "Приготовить","гуляш","с овощами","в обед"
end
act "Ужин":
  gosub "Приготовить","салат","с креветками","на ужин"
end
</sxh>

Иногда нам нужно не только передать данные на локацию, но и получить с неё какие-то данные назад. Для этого случая нужно воспользоваться специальной функцией ''%%FUNC%%''.

Как и ''%%GOSUB%%'', эта функция вызывает локацию, чтобы выполнить на ней какой-то код, однако, в отличие от ''%%GOSUB%%'', ''%%FUNC%%'' может вернуть значение из локации.

Чтобы локация, вызванная с помощью ''%%FUNC%%'', вернула какое-то значение, мы должны на этой локации присвоить это значение переменной ''%%RESULT%%''. Например, мы хотим написать локацию, на которую будем передавать число, и чтобы эта локация возвращала нам квадрат переданного числа (то есть число умноженное на само себя). Назовём эту локацию ''%%"sqr"%%'':

<sxh qsp>
!# sqr
result = args[0]*args[0]
</sxh>

Как видите, на локации ''%%"sqr"%%'' мы умножаем число из ''%%ARGS[0]%%'' само на себя, а затем результат присваиваем переменной ''%%RESULT%%''. Именно значение из переменной ''%%RESULT%%'' локация ''%%"sqr"%%'' вернёт с помощью функции ''%%FUNC%%'' на любой другой локации:

<sxh qsp>
*pl func('sqr',2) & ! на экране будет 4
*pl func('sqr',3) & ! на экране будет 9
*pl func('sqr',4) & ! на экране будет 16
</sxh>

Во всех приведённых примерах функцией является ''%%FUNC%%'', а оператором — ''%%GOSUB%%'', однако для удобства допустимо называть функциями именно локации, которые мы вызываем с помощью ''%%GOSUB%%'' или ''%%FUNC%%''. Например: «//Я написал функцию "поднять_яблоко"//».

===== Описание GOSUB =====

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

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

<sxh qsp>
  GOSUB [$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18]
</sxh>

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

Оператор имеет краткую форму ''%%GS%%'':

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

Допустимо помещать название локации и аргументы в скобки:

<sxh qsp>
  GOSUB([$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18])
</sxh>

При вызове указанной локации с помощью ''%%GOSUB%%'' происходит следующее:

  * Плеер прерывает выполнение текущего кода (например, кода текущей локации), и обращается к указанной локации
  * Базовое описание и список действий указанной локации добавляются к описанию и действиям текущей локации.
  * Выполненяется код из поля **Выполнить при посещении**
  * Затем плеер возвращается к выполнению кода, который прервал, к команде сразу после оператора ''%%GOSUB%%''.

На каждой локации автоматически создаётся собственный уникальный массив ''%%ARGS%%'', поэтому значения в этом массиве для каждой локации будут свои собственные. После выполнения кода локации, вызванной по ''%%GOSUB%%'', массив ''%%ARGS%%'' этой локации уничтожается.

**Обратите внимание!** Значения из массива ''%%ARGS%%'' с локации, вызванной через GOSUB, не транслируются в блоки ''%%ACT%%'' и гиперссылки. В блоки ''%%ACT%%'' и гиперссылки транслируются значения ''%%ARGS%%'' из текущей локации, т.е. локации, на которую был осуществлён переход с помощью операторов ''%%GOTO%%''/''%%XGOTO%%''.

<sxh qsp>
#начало
$args[0] = 'локация начало'
gosub 'переход', 'локация переход'
-

#переход
*pl $args[0]  &! На экран выведется 'локация переход'
act 'Перейти':
  goto $args[0] &! если нажмётё действие, увидите текст 'локация начало'
end
-
</sxh>

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

<sxh qsp>
! обработка локации "ход"
! На локацию не переадются аргументы
! массив ARGS пуст
GS 'ход'

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

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

Cуществует краткая форма записи, не требующая явного указания оператора ''GOSUB'':

<sxh qsp>
  @@[$локация] [аргумент 0], [аргумент 1], ... ,[аргумент 18]
</sxh>

Название локации ''[$локация]'' не заключается в кавычки и не должно содержать спецсимволов, кроме точки. Допустимо заключать аргументы в скобки.

<sxh qsp>
@@inventory.add 'ScrewDriver', 12

@@reset_screen('black-green')
</sxh>

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

Вы можете не прописывать всякий раз оператор ''GOSUB'' явно. Можно использовать более простую запись. Вот как это выглядит в общем виде:

<sxh qsp>
@@[$локация] [аргумент 0],[аргумент 1], ... ,[аргумент 18]
</sxh>

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

То есть: пишем ''%%@@%%'', затем без пробелов название локации, потом ставим пробел и через запятую перечисляем аргументы.

При такой записи необходимо соблюдать несколько правил:

  * Название локации не должно содержать пробелов, символов математических операций и специальных символов (за исключением точки)
  * Название локации не должно совпадать с ключевыми словами QSP, в том числе с названиями системных переменных.
  * Аргументы, передаваемые на локацию, можно заключать в скобки, но можно и не заключать.
  * Нельзя подставить вместо названия локации значение переменной!

Пример локации для подъёма яблока:

<sxh qsp>
!# поднять_яблоко
if яблоки['рюкзак']=0:
  addobj "Яблоки"
end
яблоки['рюкзак']+=1
яблоки[$curloc]-=1
</sxh>

Действие, которое мы пишем на любой другой локации:

<sxh qsp>
act "Взять яблоко":
  @@поднять_яблоко
end
</sxh>

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

<sxh qsp>
@@sys.init
@@hero.init
@@loc.type 'page'

@@map_set_cell [0,12], 'дерево'
</sxh>

===== Описание FUNC =====

''%%FUNC%%'' — выполнение кода указанной локации без непосредственного перехода на неё с возвращением значения.

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

<sxh qsp>
  FUNC([$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18])
  $FUNC([$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18])
  %FUNC([$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18])
</sxh>

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

Чтобы ''%%FUNC%%'' вернула строковый результат, на указанной локации нужно присвоить этот результат переменной ''%%$RESULT%%''.

Для возвращения числового результата, он должен быть присвоен переменной ''%%RESULT%%''.

Если нужно вернуть несколько значений, используется кортеж ''%%%RESULT%%''.

Следует помнить, что ''%%%RESULT%%'', ''%%$RESULT%%'' и ''%%RESULT%%'' — это одна и та же переменная, но разных типов, поэтому если вы определили на локации и ''%%%RESULT%%'', ''%%$RESULT%%'' и ''%%RESULT%%'', функция вернёт то значение, которое было записано в эту переменную последним.

Если переменной ''%%RESULT%%'' не было присвоено никакое значение, функция ничего не вернёт. И тут есть два варианта поведения плеера.

  * Если функция ''%%FUNC%%'' стоит в каком либо выражении, вместо функции будет подставлено значение по умолчанию (пустая строка или ноль в зависимости от типа самого выражения).
  * Если функция ''%%FUNC%%'' стоит сразу после неявного оператора, такой оператор будет проигнорирован, и на экран ничего выводиться не будет. Пример:

<sxh qsp>
!# локация_Н
N = 23 * 13
! ни одно значение не присваивается переменной result
</sxh>

<sxh qsp>
'строка 1'
func('локация_Н') &! ничего не выведется на экран
'строка 2'
56 + func('локация_Н') &! функция стоит в выражении. Её значение = 0. На экране будет 56
</sxh>

Не обязательно, но рекомендуется, записывать ключевое слово ''%%FUNC%%'' с символом ''%%$%%'', если функция должна вернуть текстовое значение, и с символом ''%%%%%'', если функция должна вернуть кортеж. Это улучшит читаемость кода:

<sxh qsp>
$func('срез_строки','Мы вышли из дома, когда во всех окнах погасли огни.',3,7)
func('возвести_в_степень',3,3)
$name, age, %coords = %func('get_pers', 'mjolnir')
</sxh>

При вызове указанной локации с помощью ''%%FUNC%%'' происходит следующее:

  * Плеер прерывает выполнение текущего кода (например, кода текущей локации), и обращается к указанной локации
  * Базовое описание и список действий указанной локации добавляются к описанию и действиям текущей локации.
  * Выполненяется код из поля **Выполнить при посещении**
  * Затем плеер возвращается к выполнению кода, который прервал. То есть к вычислению выражения, в котором стоит данная функция.

На каждой локации автоматически создаются свои собственные уникальные массивы ''%%ARGS%%'' и ''%%RESULT%%'', поэтому значения в этих массивах для каждой локации будут свои собственные. После выполнения кода локации, вызванной по ''%%FUNC%%'', массивы ''%%ARGS%%'' и ''%%RESULT%%'' этой локации уничтожаются.

Обратите внимание! Значения из массивов ''%%ARGS%%'' и ''%%RESULT%%'' с локации, вызванной через ''%%FUNC%%'', не транслируются в блоки ''%%ACT%%'' и гиперссылки. В блоки ''%%ACT%%'' и гиперссылкитранслируются значения ''%%ARGS%%'' и ''%%RESULT%%'' из текущей локации, т.е. локации, на которую был осуществлён переход с помощью операторов ''%%GOTO%%''/''%%XGOTO%%''.

Примеры:

<sxh qsp>
!Обработка локации "поднять_яблоко" как функции. 
!Массив ARGS пуст. 
!Результат передается через RESULT
!и записывается в переменную яблоки
яблоки = FUNC('поднять_яблоко')

!обработка локации с названием в $name как функции. ARGS[0] равен 1.
PL FUNC($name, 1) * 78

!обработка локации с названием в $name как функции. 
!$ARGS[0] содержит строку "строка", ARGS[1] равен 2.
MSG "text" + FUNC($name, "строка", 2)
</sxh>

==== Неявный вызов функции FUNC ====

Вы можете не прописывать всякий раз функцию ''%%FUNC%%'' явно. Можно использовать более простую запись. Вот как это выглядит в общем виде:

<sxh qsp>
@[$локация]([аргумент 0],[аргумент 1], ... ,[аргумент 18])
</sxh>

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

То есть: пишем символ ''%%@%%'', затем без пробелов название локации, и сразу за названием локации в скобках через запятую перечисляем аргументы.

При такой записи необходимо соблюдать несколько правил:

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

Примеры:

<sxh qsp>
*pl @sqr(2) & ! на экране будет 4
*pl @sqr(3) & ! на экране будет 9
*pl @sqr(4) & ! на экране будет 16

! функция не принимает аргументов
*pl @PI() &! можно указать пустые скобки
*pl  @PI   &! можно не указывать пустые скобки

степень = @возвести_в_степень(3,3)

! пример вложения функций и участие их в выражениях
point = @queue.addPoint($next[i],new_cost+@hevr.est($next[i],$args[0]))

! пример генерации гиперссылки с помощью локации-функции:
@html.link('Информация об игре', {goto 'game_info'}) + @BR
! локация-функция BR не принимает аргументов...........^^^
</sxh>

Если подобный неявный вызов сочетается с использованием неявного оператора, а на локации при этом НЕ присваивается значение переменной ''%%RESULT%%'', неявный вызов функции будет работать как ''%%GOSUB%%'':

Локация ''%%"поднять_яблоко"%%'':

<sxh qsp>
!# поднять_яблоко
if яблоки['рюкзак']=0:
  addobj "Яблоки"
end
яблоки['рюкзак']+=1
яблоки[$curloc]-=1
</sxh>

Действие, которое мы пишем на любой другой локации:

<sxh qsp>
act "Взять яблоко":
  @поднять_яблоко & ! в данном случае поведение функции будет идентично поведению GOSUB
end
</sxh>

===== Ранний выход. Оператор EXIT =====

Чтобы прервать выполнение текущего кода и выйти из вызванной с помощью ''%%GOSUB%%'' или ''%%FUNC%%'' локации, используйте оператор ''%%EXIT%%''.

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

Пример:

<sxh qsp>
if args[0] = 0: exit
</sxh>

===== Локальные переменные =====

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

См. раздел "Локальные переменные" в разделе [[help:variables|Переменные]].

===== Заключение =====

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

Так же см. [[https://aleksversus.github.io/howdo_faq/docs/articles/operators_funcs_args/|большую статью по операторам, функциям и аргументам]].

[[help:jump|Вперёд: Переходы внутри локации]]
Документация QSPСайтФорум

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

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

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

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