Merge Add GET_PLAYER_PEER_STATISTICS to get useful peer stats (pr-3162)

a7d4410 - feat(server): add `GET_PLAYER_PEER_STATISTICS` to get useful peer stats

Author: prikolium-cfx

code/components/citizen-server-impl/include/GameServerNet.h

@@ -17,14 +17,41 @@ enum NetPacketType
 namespace fx
 {
 	class GameServer;
+
+	enum ENetPeerStatistics : uint8_t
+	{
+		// PacketLoss will only update once every 10 seconds, use PacketLossEpoch if you want the time
+		// since the last time the packet loss was updated.
+
+		// the amount of packet loss the player has, needs to be scaled with PACKET_LOSS_SCALE
+		PacketLoss = 0,
+		// The variance in the packet loss
+		PacketLossVariance = 1,
+		// The time since the last packet update in ms, relative to the peers connection time
+		PacketLossEpoch = 2,
+		// The mean amount of time it takes for a packet to get to the client (ping)
+		RoundTripTime = 3,
+		// The variance in the round trip time
+		RoundTripTimeVariance = 4,
+		// Despite their name, these are only updated once every 5 seconds, you can get the last time this was updated with PacketThrottleEpoch
+		// The last recorded round trip time of a packet
+		LastRoundTripTime = 5,
+		// The last round trip time variance
+		LastRoundTripTimeVariance = 6,
+		// The time since the last packet throttle update, relative to the peers connection time
+		PacketThrottleEpoch = 7,
+
+		MAX
+	};
+
 	class NetPeerBase : public fwRefCountable
 	{
 	public:
 		virtual int GetId() = 0;
 
 		virtual int GetPing() = 0;
 
-		virtual int GetPingVariance() = 0;
+		virtual uint32_t GetENetStatistics(ENetPeerStatistics statisticType) = 0;
 
 		virtual net::PeerAddress GetAddress() = 0;
 

code/components/citizen-server-impl/src/GameServerNet.ENet.cpp

@@ -105,7 +105,8 @@ namespace fx
 			return peer->roundTripTime;
 		}
 
-		virtual int GetPingVariance() override
+		// Used by the scripting API to get useful statistics
+		virtual uint32_t GetENetStatistics(ENetPeerStatistics statisticType)
 		{
 			auto peer = GetPeer();
 
@@ -114,7 +115,29 @@ namespace fx
 				return 0;
 			}
 
-			return peer->roundTripTimeVariance;
+			switch (statisticType)
+			{
+				case PacketLoss:
+					return peer->packetLoss;
+				case PacketLossVariance:
+					return peer->packetLossVariance;
+				case PacketLossEpoch:
+					return peer->packetLossEpoch;
+				case RoundTripTime:
+					return peer->roundTripTime;
+				case RoundTripTimeVariance:
+					return peer->roundTripTimeVariance;
+				case LastRoundTripTime:
+					return peer->lastRoundTripTime;
+				case LastRoundTripTimeVariance:
+					return peer->lastRoundTripTimeVariance;
+				case PacketThrottleEpoch:
+					return peer->packetThrottleEpoch;
+				case PacketsSent:
+					return peer->packetsSent;
+				default:
+					return 0;
+			}
 		}
 
 		virtual net::PeerAddress GetAddress() override

code/components/citizen-server-impl/src/PlayerScriptFunctions.cpp

@@ -116,6 +116,27 @@ static void CreatePlayerCommands()
 		return int(peer->GetPing());
 	}));
 
+	fx::ScriptEngine::RegisterNativeHandler("GET_PLAYER_PEER_STATISTICS", MakeClientFunction([](fx::ScriptContext& context, const fx::ClientSharedPtr& client)
+	{
+		const int peerStatistic = context.GetArgument<uint8_t>(1);
+
+		if (peerStatistic >= fx::ENetPeerStatistics::MAX)
+		{
+			throw std::runtime_error(va("Argument 1 is out of range, max peer statistics is %d, got %d", fx::ENetPeerStatistics::MAX - 1, peerStatistic));
+		}
+
+		fx::NetPeerStackBuffer stackBuffer;
+		gscomms_get_peer(client->GetPeer(), stackBuffer);
+		auto peer = stackBuffer.GetBase();
+
+		if (!peer)
+		{
+			return 0;
+		}
+
+		return static_cast<int>(peer->GetENetStatistics(static_cast<fx::ENetPeerStatistics>(peerStatistic)));
+	}));
+
 	fx::ScriptEngine::RegisterNativeHandler("GET_PLAYER_LAST_MSG", MakeClientFunction([](fx::ScriptContext& context, const fx::ClientSharedPtr& client)
 	{
 		return (msec() - client->GetLastSeen()).count();

ext/native-decls/GetPlayerPeerStatistics.md

@@ -0,0 +1,79 @@
+---
+ns: CFX
+apiset: server
+---
+## GET_PLAYER_PEER_STATISTICS
+
+```c
+int GET_PLAYER_PEER_STATISTICS(char* playerSrc, int peerStatistic);
+```
+
+```cpp
+const int ENET_PACKET_LOSS_SCALE = 65536;
+
+enum PeerStatistics
+{
+	// PacketLoss will only update once every 10 seconds, use PacketLossEpoch if you want the time
+	// since the last time the packet loss was updated.
+
+	// the amount of packet loss the player has, needs to be scaled with PACKET_LOSS_SCALE
+	PacketLoss = 0,
+	// The variance in the packet loss
+	PacketLossVariance = 1,
+	// The time since the last packet update in ms, relative to the peers connection time
+	PacketLossEpoch = 2,
+	// The mean amount of time it takes for a packet to get to the client (ping)
+	RoundTripTime = 3,
+	// The variance in the round trip time
+	RoundTripTimeVariance = 4,
+	// Despite their name, these are only updated once every 5 seconds, you can get the last time this was updated with PacketThrottleEpoch
+	// The last recorded round trip time of a packet
+	LastRoundTripTime = 5,
+	// The last round trip time variance
+	LastRoundTripTimeVariance = 6,
+	// The time since the last packet throttle update, relative to the peers connection time
+	PacketThrottleEpoch = 7,
+};
+```
+
+These statistics only update once every 10 seconds.
+
+## Parameters
+* **playerSrc**: The player to get the stats of
+* **peerStatistic**: The statistic to get, this will error if its out of range
+
+## Return value
+See `ENetStatisticType` for what this will return.
+
+## Examples
+```js
+
+setInterval(() => {
+	const ENET_PACKET_LOSS_SCALE = 65536;
+
+	const PLAYER_SERVER_ID = 1;
+
+	const packetLoss = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 0 /* PacketLoss */);
+	const packetLossVariance = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 1 /* PacketLossVariance */);
+	const packetLossEpoch = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 2 /* PacketLossEpoch */)
+	const rtt = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 3 /* RoundTripTime */);
+	const rttVariance = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 4 /* RoundTripTimeVariance */);
+	const lastRtt = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 5 /* LastRoundTripTime */);
+	const lastRttVariance = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 6 /* LastRoundTripTimeVariance */);
+	const packetThrottleEpoch = GetPlayerPeerStatistics(PLAYER_SERVER_ID, 7 /* PacketThrottleEpoch */);
+
+	console.log(`packetLoss: ${packetLoss}`);
+	console.log(`packetLossVariance: ${packetLossVariance}`);
+	console.log(`packetLossEpch: ${packetLossEpoch}`);
+
+	console.log(`packetLossScaled: ${packetLoss / ENET_PACKET_LOSS_SCALE}`);
+	console.log(`packetLossVarianceScaled: ${packetLossVariance / ENET_PACKET_LOSS_SCALE}`);
+
+	console.log(`rtt: ${rtt}`);
+	console.log(`rttVariance: ${rttVariance}`);
+
+	console.log(`lastRtt: ${lastRtt}`);
+	console.log(`lastRttVariance: ${lastRttVariance}`);
+	console.log(`packetThrottleEpoch: ${packetThrottleEpoch}`);
+}, 10000)
+```

ext/native-decls/GetPlayerPing.md

@@ -8,8 +8,10 @@ apiset: server
 int GET_PLAYER_PING(char* playerSrc);
 ```
 
+See [GET_PLAYER_PEER_STATISTICS](#_0x9A928294) if you want more detailed information, like packet loss, and packet/rtt variance
 
 ## Parameters
 * **playerSrc**: 
 
 ## Return value
+Returns the mean amount of time a packet takes to get to the client