easy.math.qsp v. 3.2.0

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

Разрабатывалась для плееров версий 5.9.0 — это: классический плеер версии 5.9.0 и qSpider версии [1.2.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.dergb - получает составляющие цвета на основе числового кода цвета QSP.
   • em.str.get_word - из строки вида aaa|bbb|ccc|...|yyy|zzz вычленяется подстрока, стоящая в указанной позиции.
   • em.str.in_regexp - преобразует обычную строку к регулярному выражению, экранируя символы, являющиеся в регулярках специальными.
   • em.tag.get_cont - получает значение сдвоенного тега.
   • em.tag.get_num - получает значение одиночного тега.
   • em.var.get_type - получение типа переменной.

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

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

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

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

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

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

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

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

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

   • em.arr.print - вывод содержимого всех элементов массива в виде текста
   • em.fewArrs.print - вывод содержимого нескольких массивов.
   • em.arr.insert - вставка элемента в массив со сдвигом ячеек вправо.
   • em.arr.clear - удаление всех элементов массива, соответствующих указанному значению.
   • em.arr.concatenate - объединение двух массивов в массив кортежей.
   • em.arr.enumerate - на основе исходного массива генерирует массив кортежей типа [значение, индекс].
   • em.arr.few_kill - удаление нескольких элементов массива одной командой.
   • em.arr.fill - упрощённое заполнение массива значениями;
   • em.arr.fill_rand - заполнение элементов массива случайными числами
   • em.arr.fill_strt - заполнение элементов массива подряд идущими числами.
   • em.arr.sort - многофункциональная сортировка содержимого массива.
   • em.arr.restand - перетасовка элементов массива в соответствии с таблицей перестановки.
   • em.arr.desort - операция обратная сортировке.
   • em.arr.simpl - сравнение содержимого двух массивов.
   • em.arr.find - поиск максимального или минимального значения числового массива по указанной области и в заданных пределах.

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

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

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

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

9. Работа с HTML

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

10. Работа с HTML

    • em.tpl.get - получает элемент кортежа по индексу.
    • em.tpl.unzip - распаковывает кортеж в массив.

Перспективы

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