add mat4 library

doc/en/scripting.md

@@ -7,6 +7,8 @@ Subsections:
 - [User input](scripting/user-input.md)
 - [Filesystem and serialization](scripting/filesystem.md)
 - [UI properties and methods](scripting/ui.md)
+- [Libraries](#)
+    - [mat4](scripting/builtins/libmat4.md)
 - [Module core:bit_converter](scripting/modules/core_bit_converter.md)
 - [Module core:data_buffer](scripting/modules/core_data_buffer.md)
 - [Module core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)

doc/en/scripting/builtins/libmat4.md

@@ -0,0 +1,100 @@
+# *mat4* library
+
+*mat4* contains a set of functions for work with transformation 4x4 matrices.
+
+Most functions have several options for argument lists (overloads).
+
+## Data types
+
+Type conventions will be used on this page.
+- vector - an array of three or four numbers
+- vec3 - array of three numbers
+- matrix - array of 16 numbers - matrix
+
+>[!ATTENTION]
+> Type annotations are part of the documentation and are not present in Lua.
+
+## Identity matrix - *mat4.idt(...)*
+
+```lua
+-- creates an identity matrix
+mat4.idt()
+
+-- writes an identity matrix to dst
+mat4.idt(dst: matrix)
+```
+
+## Matrix multiplication - *mat4.mul(...)*
+
+```lua
+-- returns the result of matrix multiplication
+mat4.mul(a: matrix, b: matrix)
+-- writes the result of matrix multiplication to dst
+mat4.mul(a: matrix, b: matrix, dst: matrix)
+
+-- returns the result of multiplying a matrix and a vector
+mat4.mul(a: matrix, v: vector)
+-- writes the result of matrix and vector multiplication to dst
+mat4.mul(a: matrix, v: vector, dst: vector)
+```
+
+## Matrix inversion - *mat4.inverse(...)*
+
+```lua
+-- returns the result of matrix inversion
+mat4.inverse(m: matrix)
+-- writes the result of matrix inversion to dst
+mat4.inverse(m: matrix, dst: matrix)
+```
+
+## Matrix transposition - *mat4.transpose(...)*
+
+```lua
+-- returns the result of matrix transposition
+mat4.transpose(m: matrix)
+-- writes the result of matrix transposition to dst
+mat4.transpose(m: matrix, dst: matrix)
+```
+
+## Offset - *mat4.translate(...)*
+
+```lua
+-- creates a translation matrix
+mat4.translate(translation: vec3)
+-- returns the result of applying a translation to matrix m
+mat4.translate(m: matrix, translation: vec3)
+-- writes the result of applying a translation to matrix m to dst
+mat4.translate(m: matrix, translation: vec3, dst: matrix)
+```
+## Scaling - *mat4.scale(...)*
+
+```lua
+-- creates a scaling matrix
+mat4.scale(scale: vec3)
+-- returns the result of applying scaling to matrix m
+mat4.scale(m: matrix, scale: vec3)
+-- writes the result of applying scaling to matrix m to dst
+mat4.scale(m: matrix, scale: vec3, dst: matrix)
+```
+
+## Rotation - *mat4.rotate(...)*
+
+The angle of rotation is indicated in degrees.
+
+```lua
+-- creates a rotation matrix (angle - rotation angle) along a given axis (axis is an unit vector)
+mat4.rotate(axis: vec3, angle: number)
+-- returns the result of applying rotation to matrix m
+mat4.rotate(m: matrix, axis: vec3, angle: number)
+-- writes the result of applying rotation to matrix m to dst
+mat4.rotate(m: matrix, axis: vec3, angle: number, dst: matrix)
+```
+
+## Translation to string - *mat4.tostring(...)*
+
+```lua
+-- returns a string representing the contents of the matrix
+mat4.tostring(m: matrix)
+-- returns a string representing the contents of the matrix, human-readable if multiline = true
+mat4.tostring(m: matrix, multiline: bool)
+```

doc/ru/scripting.md

@@ -7,6 +7,8 @@
 - [Пользовательский ввод](scripting/user-input.md)
 - [Файловая система и сериализация](scripting/filesystem.md)
 - [Свойства и методы UI элементов](scripting/ui.md)
+- [Библиотеки](#)
+    - [mat4](scripting/builtins/libmat4.md)
 - [Модуль core:bit_converter](scripting/modules/core_bit_converter.md)
 - [Модуль core:data_buffer](scripting/modules/core_data_buffer.md)
 - [Модули core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)

doc/ru/scripting/builtins/libmat4.md

@@ -0,0 +1,100 @@
+# Библиотека *mat4*
+
+*mat4* содержит набор функций для работы с матрицами трансформации размерностью 4x4.
+
+Большинство функций имеют несколько вариантов списка агрументов (перегрузок).
+
+## Типы данных
+
+На данной странице будут использоваться условные обозначения типов.
+- vector - массив из трех или четырех чисел
+- vec3 - массив из трех чисел
+- matrix - массив из 16 чисел - матрица
+
+>[!ATTENTION]
+> Аннотации типов являются частью документации и не указываются при вызове использовании.
+
+## Единичная матрица - *mat4.idt(...)*
+
+```lua
+-- создает единичную матрицу
+mat4.idt()
+
+-- записывает единичную матрицу в dst
+mat4.idt(dst: matrix)
+```
+
+## Умножение матриц - *mat4.mul(...)*
+
+```lua
+-- возвращает результат умножения матриц
+mat4.mul(a: matrix, b: matrix)
+-- записывает результат умножения матриц в dst
+mat4.mul(a: matrix, b: matrix, dst: matrix)
+
+-- возвращает результат умножения матрицы и вектора
+mat4.mul(a: matrix, v: vector)
+-- записывает результат умножения матрицы и вектора в dst
+mat4.mul(a: matrix, v: vector, dst: vector)
+```
+
+## Инверсия матрицы - *mat4.inverse(...)*
+
+```lua
+-- возвращает результат инверсии матрицы
+mat4.inverse(m: matrix)
+-- записывает результат инверсии матрицы в dst
+mat4.inverse(m: matrix, dst: matrix)
+```
+
+##  Транспонирование матрицы - *mat4.transpose(...)*
+
+```lua
+-- возвращает результат транспонирования матрицы
+mat4.transpose(m: matrix)
+-- записывает результат транспонирования матрицы в dst
+mat4.transpose(m: matrix, dst: matrix)
+```
+
+## Смещение - *mat4.translate(...)*
+
+```lua
+-- создает матрицу смещения
+mat4.translate(translation: vec3)
+-- возвращает результат применения смещения к матрице m
+mat4.translate(m: matrix, translation: vec3)
+-- записывает результат применения смещения к матрице m в dst
+mat4.translate(m: matrix, translation: vec3, dst: matrix)
+```
+## Масштабирование - *mat4.scale(...)*
+
+```lua
+-- создает матрицу масштабирования
+mat4.scale(scale: vec3)
+-- возвращает результат применения масштабирования к матрице m
+mat4.scale(m: matrix, scale: vec3)
+-- записывает результат применения масштабирования к матрице m в dst
+mat4.scale(m: matrix, scale: vec3, dst: matrix)
+```
+
+## Вращение - *mat4.rotate(...)*
+
+Угол поворота (angle) указывается в градусах.
+
+```lua
+-- создает матрицу поворота (angle - угол поворота) по заданной оси (axis - единичный вектор)
+mat4.rotate(axis: vec3, angle: number)
+-- возвращает результат применения вращения к матрице m
+mat4.rotate(m: matrix, axis: vec3, angle: number)
+-- записывает результат применения вращения к матрице m в dst
+mat4.rotate(m: matrix, axis: vec3, angle: number, dst: matrix)
+```
+
+## Перевод в строку - *mat4.tostring(...)*
+
+```lua
+-- возвращает строку представляющую содержимое матрицы
+mat4.tostring(m: matrix)
+-- возвращает строку представляющую содержимое матрицы, многострочную, если multiline = true
+mat4.tostring(m: matrix, multiline: bool)
+```

src/logic/scripting/lua/api_lua.hpp

@@ -17,6 +17,7 @@ extern const luaL_Reg inputlib [];
 extern const luaL_Reg inventorylib [];
 extern const luaL_Reg itemlib [];
 extern const luaL_Reg jsonlib [];
+extern const luaL_Reg mat4lib [];
 extern const luaL_Reg packlib [];
 extern const luaL_Reg playerlib [];
 extern const luaL_Reg timelib [];