easy.math.qsp v. 3.1.0

Библиотека математических функций для Quest Soft Player

Разрабатывалась для плееров версий 5.8.0 — это: классический плеер версии 5.8.0 и qSpider версии 0.0.12 и выше. Не гарантируется правильная работа на плеерах иных версий. Некоторые функции имеют ограничения на значение числовых аргументов, это связано с используемыми плеером библиотеками. Для разных версий плеера могут быть разные ограничения, поэтому внимательно читайте документацию к плееру, под который разрабатываете игру.

Существует ветка 2.x.x библиотеки для плееров версии 5.7.0. Она может использоваться и на плеерах версии 5.8.0 при некоторой доработке, но библиотека ветки 3.x.x в плеерах версии 5.8.0 работает эффективнее.

Поддержать проект можно, подписавшись на Boosty: aleksversus.

Подключение и использование

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

Чтобы использовать функции библиотеки при написании своей игры, сделайте следующее:

1. Скачайте архив с библиотекой со страницы релизов, и распакуйте в папку, где лежит ваша игра. В папке с вашей игрой должна появиться папка "lib".

2. В своей игре на самой первой локации, в поле "выполнить при посещении" введите

   inclib 'lib\easy.math.qsp'
3. Теперь вы можете пользоваться функциями библиотеки.

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

Исключением являются функции, результат которых записывается в массив. Такие функции вызываются оператором GOSUB, или GS.

Аргументы могут быть текстовыми или числовыми в зависимости от требований и назначения функции.

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

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

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

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

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

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

Работа с исходниками

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

Сборку рекомендуется осуществлять через билдер в Sublime Text из пакета QSP для SublimeText.

При включенном препроцессоре необходимо подключить файл 00_sets/_variables.qsps_ к сборке, чтобы все функции добавились в модуль, либо написать собственный файл с метками нужных функций и так же подключить его к сборке. Для примера, можно взять project.json из исходников.

История версий

Функции

1. Вспомогательные функции

   • em.str.getWord - из строки вида aaa|bbb|ccc|...|yyy|zzz вычленяется подстрока, стоящая в указанной позиции.
   • em.tag.getNum - получает значение одиночного тега.
   • em.tag.getCont - получает значение сдвоенного тега.
   • em.maxVar - поиск названия переменной среди перечисленных, которая содержит наибольшее значение.
   • em.minVar - поиск названия переменной среди перечисленных, которая содержит наименьшее значение.
   • em.var.getType - получение типа переменной.
   • em.deRGB - получает составляющие цвета на основе числового кода цвета QSP.

2. Операции над вещественными (дробными) числами

   • em.dz - отсечение нулей в дробной части числа
   • em.indiv - рациональное частное от деления двух целых чисел
   • em.undiv - превращает рациональное число в целое
   • em.divdigs - получает разрядность дробной части числа
   • em.round - округляет рациональное число.
   • em.add - вычисление суммы рациональных чисел.
   • em.mult - вычисление произведения рациональных чисел.
   • em.div - вычисление частного от деления рациональных чисел.
   • em.simpl - сравнение рациональных чисел.
   • em.sqrt - вычисление корня квадратного.

3. Логические операции

   • em.byte.add - "логическое" сложение
   • em.byte.dev - "логическое" вычитание

4. Операции над текстом

   • em.zero - генерирует строку одинаковых символов
   • em.str.random - генерирует строку случайных символов
   • em.arr.search - производит поиск элемента массива, содержащего строку, соответствующую регулярному выражению.
   • em.str.inArr - из блока текста выбирает все строки между указанными разделителями и помещает их в указанный массив.
   • em.str.widetrim - удаление прилегающих пробелов, символов табуляции и переводов строк, или символов преформатирования.
   • em.str.thin - разрежение строки строкой-разделителем.
   • em.str.slice - вырезает из строки подстроку по номерам символов.
   • em.gen_uuid - генерирует UUID-подобный идентификатор.

5. Операции над шестнадцатеричными числами

   • em.hex.inDec - перевод из шестнадцатеричной системы в десятеричную
   • em.hex.add - сложение двух шестнадцатеричных чисел
   • em.dec.inHex - перевод из десятеричной системы в шестнадцатеричную
   • em.dec.inCol - превращает десятеричное число в шестнадцатеричное
   • em.col.add - изменение цвета, записанного в шестнадцатеричном RGB.
   • em.col.inRGB - преобразование цвета из формата RRGGBB в формат rgb понятный QSP.
   • em.col.inv - инвертирование цвета в формате RRGGBB, т.е. преобразование цвета к совершенно противоположному.

6. Операции над массивами

   • em.arr.print - вывод содержимого всех элементов массива в виде текста
   • em.fewArrs.print - вывод содержимого нескольких массивов.
   • em.arr.insert - вставка элемента в массив со сдвигом ячеек вправо.
   • em.arr.clear - удаление всех элементов массива, соответствующих указанному значению.
   • em.arr.chType - изменение типа массива.
   • em.arr.fill - упрощённое заполнение массива значениями;
   • em.arr.randFill - заполнение элементов массива случайными числами
   • em.arr.strtFill - заполнение элементов массива подряд идущими числами.
   • em.arr.sort - многофункциональная сортировка содержимого массива.
   • em.arr.restand - перетасовка элементов массива в соответствии с таблицей перестановки.
   • em.arr.deSort - операция обратная сортировке.
   • em.arr.simpl - сравнение содержимого двух массивов.
   • em.arr.find - поиск максимального или минимального значения числового массива по указанной области и в заданных пределах.

7. Операции над целыми числами

   • em.even - округление целых чисел до указанной разрядности
   • em.summ - подсчёт суммы всех элементов массива.
   • em.digs - получение разрядности целого числа
   • em.exp - возведение целого числа в степень.
   • em.abs - модуль от разности. c=|a-b|
   • em.random - случайное число в указанных промежутках.
   • em.log - логарифмирование по указанному основанию.

8. Работа с координатной сеткой

   • em.map.cell.getCoords - определяет координаты ячейки по текущему номеру ячейки.

9. Работа с HTML

   • em.html.clr_pref - очищает текст с HTML-разметкой от символов преформатирования.
   • em.html.to_mnemonics - заменяет в тексте с HTML-разметкой символы < и > на соответствующие мнемоники.

Перспективы

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