Различия

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

--- help:organizing [2013/11/01 05:37]
newsash
+++ help:organizing [2024/10/14 11:40] (текущий)
aleks_versus обновление 5.9.0
@@ Строка 1: / Строка 1: @@
-[[help:conditional|Назад: Условные выражения]]
+[[help:conditional|Назад: Условия]]
-=====Упорядочивание кода и циклы=====
-  * **GOSUB** //[$локация]//**,**//[параметр 1]//**,**//[параметр 2]//**, ...**
+====== Пользовательские функции и процедуры ======
-  * **GS** //[$локация]//**,**//[параметр 1]//**,**//[параметр 2]//**, ...** - обработка локации с названием //[$локация]//.
-    * Основное описание и список действий локации __//добавляются//__ к описанию и действиям старой локации.
+===== Общая информация о GOSUB и FUNC =====
-    * Происходит выполнение операторов в поле "Выполнить при посещении"
-    * Переданные параметры хранятся в массиве ARGS. Максимальное количество параметров - **9**((10 включая имя локации)).
+Сам принцип написания игр на **QSP** предполагает, что игра будет состоять из отдельных блоков кода — локаций. Эти локации могут быть связаны между собой переходами с помощью операторов ''%%GOTO%%'' и ''%%XGOTO%%''. Таким образом в **QSP** реализуется перемещение по игре, например, перемещение с места на место, или по главам интерактивной истории.
-    * Затем продолжение выполнения программы со следующей команды после GS/GOSUB.
-    * //Примеры://<sxh qsp>
+Однако иногда нам необходимо использовать локации не как локации мест, не как главы или страницы, а для того, чтобы иметь возможность выполнять повторяющиеся фрагменты кода. Например, мы пишем на нескольких разных локациях действие подъёма яблок. И нам нужно, чтобы это действие увеличивало число яблок у нас в рюкзаке, уменьшало на соответствующей локации и добавляло предмет "Яблоки", если мы не поднимали ещё ни одного яблока.
-!обработка локации "ход". Массив ARGS пуст.
+В принципе мы это можем сделать, просто копируя на каждую локацию вот такое действие:
+<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]%%'', и т.д. соответственно. После обработки локации предыдущие значения ''%%ARGS%%'' восстанавливаются. Использование аргументов не обязательно.
+Оператор имеет краткую форму ''%%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 'ход'
-!обработка локации с названием из переменной $loc
+!обработка локации с названием из переменной $location
-!Передаётся один параметр - ARGS[0] равен 1.
+!Передаётся один параметр - args[0] равен 1.
-GS $loc,1
+GS $location,1
 !обработка локации "ход" с передачей 3-х параметров.
-! $ARGS[0] = $var (значению), ARGS[1] = 2,
+! $args[0] = $var (значению), args[1] = 2,
-! $ARGS[2] = "данные". Обратите внимание на символы '$'.
+! $args[2] = "данные". Обратите внимание на символы '$'.
 GS 'ход',$var,2,'данные'
 </sxh>
-  * **FUNC(**//[$локация]//**,**//[параметр 1]//**,**//[параметр 2]//**, ...)** - обработка локации с названием //[$локация]// аналогично оператору GS (GOSUB), но с возвращением значения.
-    * Основное описание и список действий локации __//добавляются//__ к описанию и действиям старой локации.
+===== Описание FUNC =====
-    * Происходит выполнение операторов в поле "Выполнить при посещении"
-    * Переданные параметры хранятся в массиве ARGS. Максимальное количество параметров - **9**((10 включая имя локации)).
+''%%FUNC%%'' — выполнение кода указанной локации без непосредственного перехода на неё с возвращением значения.
-    * Результат функции равен значению //$RESULT// при возврате строкового значения или //RESULT// при возврате числового значения.
-    * Если при обработке локации были установлены и //RESULT//, и //$RESULT//, то предпочтение отдаётся строковому значению.
+Общая запись:
-    * После обработки локации предыдущие значения ARGS и RESULT восстанавливаются.
-    * //Примеры://<sxh qsp>
+<sxh qsp>
-PL 4 + FUNC('функция') - обработка локации "функция" как функции. Массив ARGS пуст. Результат передается через $RESULT или RESULT, в зависимости от кода обрабатываемой локации.
+  FUNC([$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18])
-PL FUNC($name, 1) * 78 - обработка локации с названием в $name как функции. ARGS[0] равен 1.
+  $FUNC([$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18])
-MSG "text" + FUNC($name, "строка", 2) - обработка локации с названием в $name как функции. $ARGS[0] содержит строку "строка", ARGS[1] равен 2.
+  %FUNC([$локация],[аргумент 0],[аргумент 1], ... ,[аргумент 18])
 </sxh>
-EXIT - завершение выполнения текущего кода (преждевременный выход из подпрограммы / обработчика какого-либо события...).
+, где ''%%[$локация]%%'' — это название локации, код которой мы хотим выполнить без непосредственного перехода на неё. Аргументы ''%%[аргумент 0]%%'', ''%%[аргумент 1]%%'' и т.д. могут использоваться на этой локации, их значения автоматически помещаются в ячейки массива ''%%ARGS[0]%%'', ''%%ARGS[1]%%'', и т.д. соответственно. Название локации и аргументы должны обязательно заключаться в скобки.
+Чтобы ''%%FUNC%%'' вернула строковый результат, на указанной локации нужно присвоить этот результат переменной ''%%$RESULT%%''.
+Для возвращения числового результата, он должен быть присвоен переменной ''%%RESULT%%''.
-JUMP [$выражение] - переход в текущем коде (при обработке локации / выбора действия) на метку [$выражение]. Метка на локации обозначается как ":[название метки]". После описания метки (через "&") могут идти операторы. Если интерпретатор находит случайную метку, то он её просто игнорирует. Например:
+Если нужно вернуть несколько значений, используется кортеж ''%%%RESULT%%''.
+Следует помнить, что ''%%%RESULT%%'', ''%%$RESULT%%'' и ''%%RESULT%%'' — это одна и та же переменная, но разных типов, поэтому если вы определили на локации и ''%%%RESULT%%'', ''%%$RESULT%%'' и ''%%RESULT%%'', функция вернёт то значение, которое было записано в эту переменную последним.
+Если переменной ''%%RESULT%%'' не было присвоено никакое значение, функция ничего не вернёт. И тут есть два варианта поведения плеера.
-jump 'КонеЦ'
+  * Если функция ''%%FUNC%%'' стоит в каком либо выражении, вместо функции будет подставлено значение по умолчанию (пустая строка или ноль в зависимости от типа самого выражения).
+  * Если функция ''%%FUNC%%'' стоит сразу после неявного оператора, такой оператор будет проигнорирован, и на экран ничего выводиться не будет. Пример:
-p 'Это сообщение не будет выведено'
+<sxh qsp>
+!# локация_Н
+N = 23 * 13
+! ни одно значение не присваивается переменной result
+</sxh>
-:конец
+<sxh qsp>
+'строка 1'
+func('локация_Н') &! ничего не выведется на экран
+'строка 2'
++ func('локация_Н') &! функция стоит в выражении. Её значение = 0. На экране будет 56
+</sxh>
-p 'А это сообщение пользователь увидит'
+Не обязательно, но рекомендуется, записывать ключевое слово ''%%FUNC%%'' с символом ''%%$%%'', если функция должна вернуть текстовое значение, и с символом ''%%%%%'', если функция должна вернуть кортеж. Это улучшит читаемость кода:
+<sxh qsp>
+$func('срез_строки','Мы вышли из дома, когда во всех окнах погасли огни.',3,7)
+func('возвести_в_степень',3,3)
+$name, age, %coords = %func('get_pers', 'mjolnir')
+</sxh>
+При вызове указанной локации с помощью ''%%FUNC%%'' происходит следующее:
-С помощью оператора "JUMP" можно организовывать циклы:
+  * Плеер прерывает выполнение текущего кода (например, кода текущей локации), и обращается к указанной локации
+  * Базовое описание и список действий указанной локации добавляются к описанию и действиям текущей локации.
+  * Выполненяется код из поля **Выполнить при посещении**
+  * Затем плеер возвращается к выполнению кода, который прервал. То есть к вычислению выражения, в котором стоит данная функция.
+На каждой локации автоматически создаются свои собственные уникальные массивы ''%%ARGS%%'' и ''%%RESULT%%'', поэтому значения в этих массивах для каждой локации будут свои собственные. После выполнения кода локации, вызванной по ''%%FUNC%%'', массивы ''%%ARGS%%'' и ''%%RESULT%%'' этой локации уничтожаются.
+Обратите внимание! Значения из массивов ''%%ARGS%%'' и ''%%RESULT%%'' с локации, вызванной через ''%%FUNC%%'', не транслируются в блоки ''%%ACT%%''. В блоки ''%%ACT%%'' транслируются значения ''%%ARGS%%'' и ''%%RESULT%%'' из текущей локации, т.е. локации, на которую был осуществлён переход с помощью операторов ''%%GOTO%%''/''%%XGOTO%%''.
-s=0
+Примеры:
-:loop
+<sxh qsp>
+!Обработка локации "поднять_яблоко" как функции.
+!Массив ARGS пуст.
+!Результат передается через RESULT
+!и записывается в переменную яблоки
+яблоки = FUNC('поднять_яблоко')
-if s<9:
+!обработка локации с названием в $name как функции. ARGS[0] равен 1.
+PL FUNC($name, 1) * 78
-s=s+1
+!обработка локации с названием в $name как функции.
+!$ARGS[0] содержит строку "строка", ARGS[1] равен 2.
+MSG "text" + FUNC($name, "строка", 2)
+</sxh>
-pl s
+===== Ранний выход. Оператор EXIT =====
-jump 'LOOP'
+Чтобы прервать выполнение текущего кода и выйти из вызванной с помощью ''%%GOSUB%%'' или ''%%FUNC%%'' локации, используйте оператор ''%%EXIT%%''.
+''%%EXIT%%'' - завершение выполнения текущего кода (преждевременный выход из подпрограммы/обработчика какого-либо события).
+Пример:
+<sxh qsp>
+if args[0] = 0: exit
+</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]))
+</sxh>
+Если подобный неявный вызов сочетается с использованием неявного оператора, а на локации при этом НЕ присваивается значение переменной ''%%RESULT%%'', можно использовать неявный вызов функции вместо оператора ''%%GOSUB%%'':
+Локация ''%%"поднять_яблоко"%%'':
+<sxh qsp>
+!# поднять_яблоко
+if яблоки['рюкзак']=0:
+  addobj "Яблоки"
 end
+яблоки['рюкзак']+=1
+яблоки[$curloc]-=1
+</sxh>
+Действие, которое мы пишем на любой другой локации:
+<sxh qsp>
+act "Взять яблоко":
+  @поднять_яблоко & ! в данном случае поведение функции будет идентично поведению GOSUB
+end
+</sxh>
+===== Локальные переменные =====
+На любой локации вы можете назначать локальные переменные, которые будут существовать только в момент выполнения кода этих локаций, а после — автоматически уничтожаться. Значения в этих локальных переменных не пересекаются со значениями одноимённых переменных в других локациях.
+См. раздел "Локальные переменные" в разделе [[help:variables|Переменные]].
+===== Заключение =====
-p 'Всё!'
+Таким образом вы можете разбивать свой код на множество более мелких блоков, дабы избегать повторения одинаковых фрагментов. Это позволяет не только лучше структурировать код, но и улучшает его читаемость и позволяет разрабатывать его модульно, т.е. отдельными независимыми фрагментами. Это, в свою очередь, ускоряет отладку и написание больших и сложных механик для ваших игр.
+Так же см. [[https://aleksversus.github.io/howdo_faq/docs/articles/operators_funcs_args/|большую статью по операторам, функциям и аргументам]].
+[[help:jump|Вперёд: Переходы внутри локации]]
-Оператор "JUMP" также полезен во время отладки квеста, чтобы "обойти" группу операторов, которые временно не нужны.

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

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

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

Различия

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

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