Deprecate get_player_velocity and add_player_velocity (#10173)

builtin/game/features.lua

@@ -17,6 +17,7 @@ core.features = {
 	area_store_persistent_ids = true,
 	pathfinder_works = true,
 	object_step_has_moveresult = true,
+	direct_velocity_on_players = true,
 }
 
 function core.has_feature(arg)

doc/lua_api.txt

@@ -4340,6 +4340,8 @@ Utilities
           pathfinder_works = true,
           -- Whether Collision info is available to an objects' on_step (5.3.0)
           object_step_has_moveresult = true,
+          -- Whether get_velocity() and add_velocity() can be used on players (5.4.0)
+          direct_velocity_on_players = true,
       }
 
 * `minetest.has_feature(arg)`: returns `boolean, missing_features`
@@ -6118,6 +6120,19 @@ object you are working with still exists.
 
 * `get_pos()`: returns `{x=num, y=num, z=num}`
 * `set_pos(pos)`: `pos`=`{x=num, y=num, z=num}`
+* `get_velocity()`: returns the velocity, a vector.
+* `add_velocity(vel)`
+    * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
+    * In comparison to using get_velocity, adding the velocity and then using
+      set_velocity, add_velocity is supposed to avoid synchronization problems.
+      Additionally, players also do not support set_velocity.
+    * If a player:
+        * Does not apply during free_move.
+        * Note that since the player speed is normalized at each move step,
+          increasing e.g. Y velocity beyond what would usually be achieved
+          (see: physics overrides) will cause existing X/Z velocity to be reduced.
+        * Example: `add_velocity({x=0, y=6.5, z=0})` is equivalent to
+          pressing the jump key (assuming default settings)
 * `move_to(pos, continuous=false)`
     * Does an interpolated move for Lua entities for visually smooth transitions.
     * If `continuous` is true, the Lua entity will not be moved to the current
@@ -6189,11 +6204,6 @@ object you are working with still exists.
       no effect and returning `nil`.
 * `set_velocity(vel)`
     * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
-* `add_velocity(vel)`
-    * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
-    * In comparison to using get_velocity, adding the velocity and then using
-      set_velocity, add_velocity is supposed to avoid synchronization problems.
-* `get_velocity()`: returns the velocity, a vector
 * `set_acceleration(acc)`
     * `acc` is a vector
 * `get_acceleration()`: returns the acceleration, a vector
@@ -6229,16 +6239,9 @@ object you are working with still exists.
 #### Player only (no-op for other objects)
 
 * `get_player_name()`: returns `""` if is not a player
-* `get_player_velocity()`: returns `nil` if is not a player, otherwise a
+* `get_player_velocity()`: **DEPRECATED**, use get_velocity() instead.
   table {x, y, z} representing the player's instantaneous velocity in nodes/s
-* `add_player_velocity(vel)`
-    * Adds to player velocity, this happens client-side and only once.
-    * Does not apply during free_move.
-    * Note that since the player speed is normalized at each move step,
-      increasing e.g. Y velocity beyond what would usually be achieved
-      (see: physics overrides) will cause existing X/Z velocity to be reduced.
-    * Example: `add_player_velocity({x=0, y=6.5, z=0})` is equivalent to
-      pressing the jump key (assuming default settings)
+* `add_player_velocity(vel)`: **DEPRECATED**, use add_velocity(vel) instead.
 * `get_look_dir()`: get camera direction as a unit vector
 * `get_look_vertical()`: pitch in radians
     * Angle ranges between -pi/2 and pi/2, which are straight up and down

src/script/lua_api/l_base.cpp

@@ -170,10 +170,11 @@ void ModApiBase::markAliasDeprecated(luaL_Reg *reg)
 			m_deprecated_wrappers.emplace(
 				std::pair<std::string, luaL_Reg>(reg->name, original_reg));
 			reg->func = l_deprecated_function;
+		} else {
+			last_func = reg->func;
+			last_name = reg->name;
 		}
 
-		last_func = reg->func;
-		last_name = reg->name;
 		++reg;
 	}
 }

src/script/lua_api/l_object.cpp

@@ -863,12 +863,21 @@ int ObjectRef::l_add_velocity(lua_State *L)
 {
 	NO_MAP_LOCK_REQUIRED;
 	ObjectRef *ref = checkobject(L, 1);
-	LuaEntitySAO *co = getluaobject(ref);
-	if (!co)
+	v3f vel = checkFloatPos(L, 2);
+
+	ServerActiveObject *obj = getobject(ref);
+	if (obj == nullptr)
 		return 0;
-	v3f pos = checkFloatPos(L, 2);
-	// Do it
-	co->addVelocity(pos);
+
+	if (obj->getType() == ACTIVEOBJECT_TYPE_LUAENTITY) {
+		LuaEntitySAO *co = dynamic_cast<LuaEntitySAO*>(obj);
+		co->addVelocity(vel);
+	} else if (obj->getType() == ACTIVEOBJECT_TYPE_PLAYER) {
+		PlayerSAO *player = dynamic_cast<PlayerSAO*>(obj);
+		player->setMaxSpeedOverride(vel);
+		getServer(L)->SendPlayerSpeed(player->getPeerID(), vel);
+	}
+
 	return 0;
 }
 
@@ -877,11 +886,23 @@ int ObjectRef::l_get_velocity(lua_State *L)
 {
 	NO_MAP_LOCK_REQUIRED;
 	ObjectRef *ref = checkobject(L, 1);
-	LuaEntitySAO *co = getluaobject(ref);
-	if (co == NULL) return 0;
-	// Do it
-	v3f v = co->getVelocity();
-	pushFloatPos(L, v);
+
+	ServerActiveObject *obj = getobject(ref);
+	if (obj == nullptr)
+		return 0;
+
+	if (obj->getType() == ACTIVEOBJECT_TYPE_LUAENTITY) {
+		LuaEntitySAO *co = dynamic_cast<LuaEntitySAO*>(obj);
+		v3f v = co->getVelocity();
+		pushFloatPos(L, v);
+		return 1;
+	} else if (obj->getType() == ACTIVEOBJECT_TYPE_PLAYER) {
+		RemotePlayer *player = dynamic_cast<PlayerSAO*>(obj)->getPlayer();
+		push_v3f(L, player->getSpeed() / BS);
+		return 1;
+	}
+
+	lua_pushnil(L);
 	return 1;
 }
 
@@ -1082,38 +1103,6 @@ int ObjectRef::l_get_player_name(lua_State *L)
 	return 1;
 }
 
-// get_player_velocity(self)
-int ObjectRef::l_get_player_velocity(lua_State *L)
-{
-	NO_MAP_LOCK_REQUIRED;
-	ObjectRef *ref = checkobject(L, 1);
-	RemotePlayer *player = getplayer(ref);
-	if (player == NULL) {
-		lua_pushnil(L);
-		return 1;
-	}
-	// Do it
-	push_v3f(L, player->getSpeed() / BS);
-	return 1;
-}
-
-// add_player_velocity(self, {x=num, y=num, z=num})
-int ObjectRef::l_add_player_velocity(lua_State *L)
-{
-	NO_MAP_LOCK_REQUIRED;
-	ObjectRef *ref = checkobject(L, 1);
-	v3f vel = checkFloatPos(L, 2);
-
-	PlayerSAO *co = getplayersao(ref);
-	if (!co)
-		return 0;
-
-	// Do it
-	co->setMaxSpeedOverride(vel);
-	getServer(L)->SendPlayerSpeed(co->getPeerID(), vel);
-	return 0;
-}
-
 // get_look_dir(self)
 int ObjectRef::l_get_look_dir(lua_State *L)
 {
@@ -2288,10 +2277,14 @@ luaL_Reg ObjectRef::methods[] = {
 	luamethod(ObjectRef, get_properties),
 	luamethod(ObjectRef, set_nametag_attributes),
 	luamethod(ObjectRef, get_nametag_attributes),
-	// LuaEntitySAO-only
+
 	luamethod_aliased(ObjectRef, set_velocity, setvelocity),
 	luamethod(ObjectRef, add_velocity),
+	{"add_player_velocity", ObjectRef::l_add_velocity},
 	luamethod_aliased(ObjectRef, get_velocity, getvelocity),
+	{"get_player_velocity", ObjectRef::l_get_velocity},
+
+	// LuaEntitySAO-only
 	luamethod_aliased(ObjectRef, set_acceleration, setacceleration),
 	luamethod_aliased(ObjectRef, get_acceleration, getacceleration),
 	luamethod_aliased(ObjectRef, set_yaw, setyaw),
@@ -2307,8 +2300,7 @@ luaL_Reg ObjectRef::methods[] = {
 	luamethod(ObjectRef, is_player),
 	luamethod(ObjectRef, is_player_connected),
 	luamethod(ObjectRef, get_player_name),
-	luamethod(ObjectRef, get_player_velocity),
-	luamethod(ObjectRef, add_player_velocity),
+
 	luamethod(ObjectRef, get_look_dir),
 	luamethod(ObjectRef, get_look_pitch),
 	luamethod(ObjectRef, get_look_yaw),

src/script/lua_api/l_object.h

@@ -209,12 +209,6 @@ class ObjectRef : public ModApiBase {
 	// get_player_name(self)
 	static int l_get_player_name(lua_State *L);
 
-	// get_player_velocity(self)
-	static int l_get_player_velocity(lua_State *L);
-
-	// add_player_velocity(self, {x=num, y=num, z=num})
-	static int l_add_player_velocity(lua_State *L);
-
 	// get_fov(self)
 	static int l_get_fov(lua_State *L);