From 1fb0eb762d028d3a99ba1fee1969ed32861044e3 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sun, 22 Mar 2026 22:54:50 +0300
Subject: [PATCH 1/3] add entity.rigidbody.get_ground_vel

---
 res/modules/internal/stdcomp.lua                | 1 +
 src/logic/scripting/lua/libs/lib__rigidbody.cpp | 9 +++++++++
 2 files changed, 10 insertions(+)

diff --git a/res/modules/internal/stdcomp.lua b/res/modules/internal/stdcomp.lua
index db78bc7a8..4278f14f6 100644
--- a/res/modules/internal/stdcomp.lua
+++ b/res/modules/internal/stdcomp.lua
@@ -38,6 +38,7 @@ local Rigidbody = {__index={
     get_elasticity=function(self) return __rigidbody.get_elasticity(self.eid) end,
     set_mass=function(self, v) return __rigidbody.set_mass(self.eid, v) end,
     set_elasticity=function(self, v) return __rigidbody.set_elasticity(self.eid, v) end,
+    get_ground_vel=function(self) return __rigidbody.get_ground_vel(self.eid) end,
 }}
 
 local function new_Rigidbody(eid)
diff --git a/src/logic/scripting/lua/libs/lib__rigidbody.cpp b/src/logic/scripting/lua/libs/lib__rigidbody.cpp
index 52234f91e..a36f2b080 100644
--- a/src/logic/scripting/lua/libs/lib__rigidbody.cpp
+++ b/src/logic/scripting/lua/libs/lib__rigidbody.cpp
@@ -192,6 +192,14 @@ static int l_set_elasticity(lua::State* L) {
     return 0;
 }
 
+static int l_get_ground_vel(lua::State* L) {
+    if (auto entity = get_entity(L, 1)) {
+        return lua::pushvec3(L, entity->getRigidbody().hitbox.groundVelocity);
+    }
+    return 0;
+}
+
+
 const luaL_Reg rigidbodylib[] = {
     {"is_enabled", lua::wrap<l_is_enabled>},
     {"set_enabled", lua::wrap<l_set_enabled>},
@@ -217,5 +225,6 @@ const luaL_Reg rigidbodylib[] = {
     {"set_mass", lua::wrap<l_set_mass>},
     {"get_elasticity", lua::wrap<l_get_elasticity>},
     {"set_elasticity", lua::wrap<l_set_elasticity>},
+    {"get_ground_vel", lua::wrap<l_get_ground_vel>},
     {nullptr, nullptr}
 };

From 8ca74506f5c92fa815535ec6f649d05f8767a92c Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sun, 22 Mar 2026 22:56:55 +0300
Subject: [PATCH 2/3] update doc/*/scripting/ecs.md

---
 doc/en/scripting/ecs.md | 3 +++
 doc/ru/scripting/ecs.md | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/doc/en/scripting/ecs.md b/doc/en/scripting/ecs.md
index e0c6b69c6..7835d21da 100644
--- a/doc/en/scripting/ecs.md
+++ b/doc/en/scripting/ecs.md
@@ -129,6 +129,9 @@ body:set_mass(mass: number)
 body:get_elasticity() -> number
 -- Sets the body's elasticity
 body:set_elasticity(elasticity: number)
+
+-- Returns the velocity of the surface the body is on, or {0,0,0}
+body:get_ground_vel() -> vec3
 ```
 
 ### Skeleton
diff --git a/doc/ru/scripting/ecs.md b/doc/ru/scripting/ecs.md
index 50735913a..fd20523a6 100644
--- a/doc/ru/scripting/ecs.md
+++ b/doc/ru/scripting/ecs.md
@@ -129,6 +129,9 @@ body:set_mass(mass: number)
 body:get_elasticity() -> number
 -- Устанавливает упругость тела
 body:set_elasticity(elasticity: number)
+
+-- Возвращает скорость поверхности, на которой находится тело, либо {0,0,0}
+body:get_ground_vel() -> vec3
 ```
 
 ### Skeleton

From 0fcd1906260bf198f292c593230956d264256694 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sun, 22 Mar 2026 23:00:04 +0300
Subject: [PATCH 3/3] update CHANGELOG.md

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8333df403..281924189 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -78,6 +78,7 @@ Table of contents:
 - entity.rigidbody:set_elasticity
 - entity.rigidbody:set_mass
 - entity.rigidbody:set_material
+- entity.rigidbody:get_ground_vel
 - gfx.blockwraps.set_faces
 - gfx.blockwraps.set_tints
 - gui.close_menu