From 98504b9f484c5b42829d70565e9a8950f1a1b21d Mon Sep 17 00:00:00 2001
From: Cogi Asd <asadovserega2@gmail.com>
Date: Mon, 8 Jul 2024 17:11:36 +0300
Subject: [PATCH] add docs for vectors

---
 doc/ru/scripting/builtins/libvecn.md | 147 +++++++++++++++++++++++++++
 src/logic/scripting/lua/libvecn.cpp  |  18 +++-
 2 files changed, 164 insertions(+), 1 deletion(-)
 create mode 100644 doc/ru/scripting/builtins/libvecn.md

diff --git a/doc/ru/scripting/builtins/libvecn.md b/doc/ru/scripting/builtins/libvecn.md
new file mode 100644
index 00000000..d72cbb96
--- /dev/null
+++ b/doc/ru/scripting/builtins/libvecn.md
@@ -0,0 +1,147 @@
+# Библиотека Vec*n*
+
+*vecn* содержит набор функций для работы с векторами размерностью 2, 3 или 4.
+Большинство функций имеют несколько вариантов списка аргументов (перегрузок).
+
+> [!WARNING]
+>
+> vecn, где n |-> размерность вектора (2, 3, 4), т.е vec2, vec3, vec4
+> 
+
+## Типы данных
+
+На данной странице будут использоваться условные обозначения типов.
+- vector - массив из двух, трех или четырех чисел
+- vec2 - массив из двух чисел
+- vec3 - массив из трех чисел
+- vec4 - массив из четырех чисел
+
+> [!WARNING]
+>
+> Аннотации типов являются частью документации и не указываются при вызове использовании.
+
+
+## Операции с векторами
+
+#### Сложение - *vecn.add(...)*
+
+```lua
+-- возвращает результат сложения векторов
+vecn.add(a: vector, b: vector)
+
+-- возвращает результат сложения вектора и скаляра
+vecn.add(a: vector, b: number)
+```
+
+#### Вычитание - *vecn.sub(...)*
+
+```lua
+-- возвращает результат вычитания векторов
+vecn.sub(a: vector, b: vector)
+
+-- возвращает результат вычитания скаляра из вектора
+vecn.sub(a: vector, b: number)
+```
+
+#### Умножение - *vecn.mul(...)*
+
+```lua
+-- возвращает результат умножения векторов
+vecn.mul(a: vector, b: vector)
+
+-- возвращает результат умножения вектора на скаляр
+vecn.mul(a: vector, b: number)
+```
+
+#### Инверсия - *vecn.inv(...)*
+
+```lua
+-- возвращает результат инверсии (противоположный) вектора
+vecn.inv(a: vector)
+```
+
+####  Деление - *vecn.div(...)*
+
+```lua
+-- возвращает результат деления векторов
+vecn.div(a: vector, b: vector)
+
+-- возвращает результат деления вектора на скаляр
+vecn.div(a: vector, b: number)
+```
+
+#### Нормализация - *vecn.norm(...)*
+
+```lua
+-- возвращает нормализованный вектор
+vecn.norm(a: vector)
+```
+#### Длина вектора - *vecn.len(...)*
+
+```lua
+-- возвращает длину вектора
+vecn.len(a: vector)
+```
+
+#### Абсолютное значение - *vecn.abs(...)*
+
+```lua
+-- возвращает вектор с абсолютными значениями
+vecn.abs(a: vector)
+```
+
+#### Округление - *vecn.round(...)*
+
+```lua
+-- возвращает вектор с округленными значениями
+vecn.round(a: vector)
+```
+
+#### Степень - *vecn.pow(...)*
+
+```lua
+-- возвращает вектор с элементами, возведенными в степень
+vecn.pow(a: vector, b: number)
+```
+
+#### Скалярное произведение - *vecn.dot(...)*
+```lua
+-- возвращает скалярное произведение векторов
+vecn.dot(a: vector, b: vector)
+```
+
+#### Векторное произведение - *vecn.cross(...)*
+```lua
+-- возвращает векторное произведение векторов
+vecn.cross(a: vector, b: vector)
+```
+
+#### Поворот - *vecn.rot(...)*
+> [!WARNING]
+> Угол поворота (angle) указывается в радианах.
+
+```lua
+-- возвращает вектор, повернутый на заданный угол
+vecn.rot(a: vector, angle: number)
+```
+
+#### Перевод в строку - *vecn.tostring(...)*
+> [!WARNING]
+> Возвращает только тогда, когда содержимым является вектор
+```lua
+-- возвращает строку представляющую содержимое вектора
+vecn.tostring(a: vector)
+```
+
+
+## Пример
+```lua
+-- создание векторов разной размерности
+local v1_3d = {1, 2, 2}
+local v2_3d = {10, 20, 40}
+local v3_4d = {1, 2, 4, 1}
+local v4_2d = {1, 1}
+local scal = 6 -- обычный скаляр
+
+
+```
diff --git a/src/logic/scripting/lua/libvecn.cpp b/src/logic/scripting/lua/libvecn.cpp
index 4933a7f3..289b54f3 100644
--- a/src/logic/scripting/lua/libvecn.cpp
+++ b/src/logic/scripting/lua/libvecn.cpp
@@ -124,7 +124,7 @@ static int l_cross(lua::State* L) {
     const auto& b = lua::tovec<n>(L, 2);
 
     glm::vec<n, float> result_vector;
-    
+
     if (n == 2) {
         result_vector.x = a.x * b.y - a.y * b.x;
         return lua::pushnumber(L, result_vector.x);
@@ -138,6 +138,19 @@ static int l_cross(lua::State* L) {
     }
 }
 
+template<int n>
+static int l_inverse(lua::State* L) {
+    if (lua::gettop(L)!= 1) {
+        throw std::runtime_error("invalid arguments number (1 expected)");
+    }
+    const auto& vec = lua::tovec<n>(L, 1);
+    glm::vec<n, float> result_vector;
+    for (int i = 0; i < n; i++) {
+        result_vector[i] = -vec[i];
+    }
+    return lua::setvec(L, 1, result_vector);
+}
+
 template<int n>
 static int l_tostring(lua::State* L) {
     const auto& vec = lua::tovec<n>(L, 1);
@@ -166,6 +179,7 @@ const luaL_Reg vec2lib [] = {
     {"abs", lua::wrap<l_unaryop<2, glm::abs>>},
     {"round", lua::wrap<l_unaryop<2, glm::round>>},
     {"tostring", lua::wrap<l_tostring<2>>},
+    {"inv", lua::wrap<l_inverse<2>>},
     {"cross", lua::wrap<l_cross<2>>},
     {"rot", lua::wrap<l_rotate<2>>},
     {"pow", lua::wrap<l_pow<2>>},
@@ -183,6 +197,7 @@ const luaL_Reg vec3lib [] = {
     {"abs", lua::wrap<l_unaryop<3, glm::abs>>},
     {"round", lua::wrap<l_unaryop<3, glm::round>>},
     {"tostring", lua::wrap<l_tostring<3>>},
+    {"inv", lua::wrap<l_inverse<3>>},
     {"cross", lua::wrap<l_cross<3>>},
     {"rot", lua::wrap<l_rotate<3>>},
     {"pow", lua::wrap<l_pow<3>>},
@@ -200,6 +215,7 @@ const luaL_Reg vec4lib [] = {
     {"len", lua::wrap<l_scalar_op<4, glm::length>>},
     {"round", lua::wrap<l_unaryop<4, glm::round>>},
     {"tostring", lua::wrap<l_tostring<4>>},
+    {"inv", lua::wrap<l_inverse<4>>},
     {"cross", lua::wrap<l_cross<4>>},
     {"rot", lua::wrap<l_rotate<4>>},
     {"pow", lua::wrap<l_pow<4>>},