<cat>Dev</cat> <title>Networking Options, Limits and Errors</title> This page lists which Networking Options there are and how they work, all Networking Limits and all found Networking Errors and how to solve them # The Navigator This is a list containing all sections of this Page so you can navigate it easier. - [Networking Options](https://wiki.facepunch.com/gmod/Networking_Usage#networkingoptions) - [umsg (DEPRECATED)](https://wiki.facepunch.com/gmod/Networking_Usage#umsgdeprecated) - [net](https://wiki.facepunch.com/gmod/Networking_Usage#net) - [NW](https://wiki.facepunch.com/gmod/Networking_Usage#nw) - [NW2](https://wiki.facepunch.com/gmod/Networking_Usage#nw2) - [Networking Limits](https://wiki.facepunch.com/gmod/Networking_Usage#networkinglimits) - [umsg](https://wiki.facepunch.com/gmod/Networking_Usage#umsglimits) - [net](https://wiki.facepunch.com/gmod/Networking_Usage#netlimits) - [net bandwidth](https://wiki.facepunch.com/gmod/Networking_Usage#netbandwidth) - [NW](https://wiki.facepunch.com/gmod/Networking_Usage#nwlimits) - [NW2](https://wiki.facepunch.com/gmod/Networking_Usage#nw2limits) - [Networking Optimization](https://wiki.facepunch.com/gmod/Networking_Usage~edit#networkingoptimization) - [Networking Optimization](https://wiki.facepunch.com/gmod/Networking_Usage#networkingoptimization) - [sv_playerforcedupdate issue](https://wiki.facepunch.com/gmod/Networking_Usage#svplayerforcedupdateissue) - [Networking Errors](https://wiki.facepunch.com/gmod/Networking_Usage#networkingerrors) - [umsg](https://wiki.facepunch.com/gmod/Networking_Usage#umsgerrors) - [net](https://wiki.facepunch.com/gmod/Networking_Usage#neterrors) - [NW](https://wiki.facepunch.com/gmod/Networking_Usage#nwerrors) - [NW2](https://wiki.facepunch.com/gmod/Networking_Usage#nw2errors) # Networking Options ## umsg (DEPRECATED) The <page>umsg</page> library is a deprecated serverside networking library that was previously the most common way of sending information from the server to the client. In order for clients to receive an umsg, it has to use the <page>usermessage</page> library, which is shared for the client and the server. This library was used in some functions to send a message like text to the client and then to display it, and it is still used in some old functions like <page>Global.PrintMessage</page>, <page>Player:PrintMessage</page> and <page>Player:ChatPrint</page>. It is also used by the NW System to network the NW Vars. <note> umsg sent by the engine to a client can be received by it even when his net buffer is overflown / he cannot receive & sent any net messages. </note> Hello World example with the <page>umsg</page> and <page>usermessage</page> library. ```lua if SERVER then local filter = RecipientFilter() filter:AddAllPlayers() umsg.Start( "Example" ) umsg.String( "Hello World" ) umsg.End() else usermessage.Hook( "Example", function( msg ) print( msg:ReadString() ) end) end ``` --- ## net The <page>net</page> library is one of the ways to send data between client and server. One of the major advantages of the net library is the ability to send data backwards - from the client to the server. This library is commonly used in the network of values to a specific client only, or to network bigger values like Strings(<page>net.WriteString</page>) or Ints(<page>net.WriteInt</page>). You can read more about this library here: <page>Net_Library_Usage</page> and <page>Net_Library_Example</page> <note>When the ```OnRequestFullUpdate``` <page>Game_Events</page> is called the first time, <page>net</page> messages will reliably be received</note> <note> The AutoRefresh System uses the net library to network changes. Because of this, it is limited to 65536 bytes. If you exceed the Limit, it will throw an error. </note> Hello World Example with the <page>net</page> library ```lua if SERVER then util.AddNetworkString( "Example" ) net.Start( "Example" ) net.WriteString( "Hello World" ) net.Broadcast() else net.Receive( "Example", function() print( net.ReadString() ) end) end ``` --- ## NW The NW system allows for a value to be networked on an entity to all clients with the SetNW functions like <page>Entity:SetNWString</page> and the value can be returned by using the GetNW functions like <page>Entity:GetNWString</page>. It also allows to set global values with the SetGlobal* functions like <page>Global.SetGlobalString</page> and the value can be retured by using the GetGlobal* functions like <page>Global.GetGlobalString</page> <note> the value will be the same on all clients if they haven't been modified by the client. All SetNW* and SetGlobal* functions will network the value every 10 seconds after it has been set. (Because if this, It can cause massive amounts of networking if you use a bunch of NW vars.) All NW values will be accessible clientside when the <page>GM:InitPostEntity</page> hook is called SetGlobal* works internally like ```Entity(0):SetNW*``` and because of this, values set with the SetGlobal* functions can be accessed with ```Entity(0):GetNW*``` </note> Hello World Example with the NW system ```lua if SERVER then Entity( 1 ):SetNWString( "Example", "Hello World" ) else Entity( 1 ):SetNWVarProxy( "Example", function(_, _, _, value ) print( value ) end) end ``` If you want to network a table with the NW system, you can use <page>util.TableToJSON</page> to make it into a string, and then you can send it with <page>Entity:SetNWString</page> or <page>Global.SetGlobalString</page> and return it with <page>Entity:GetNWString</page> or <page>Global.GetGlobalString</page> <note>The string returned by <page>util.TableToJSON</page> should not be bigger than 255 characters. You can use the NW2 system to use up to 511 characters.</note> <example> <description>Networking a Table containing Hello World</description> <code> if SERVER then local table = { "Hello World" } SetGlobalString( "Example", util.TableToJSON( table ) ) else PrintTable( util.JSONToTable( GetGlobalString( "Example" ) ) ) end </code> <output> ```lua 1 = Hello World ``` </output> </example> --- ## NW2 The NW2 system is the successor to the NW system, but it hasn't been officially finished. It allows for values to be networked on an entity to all clients in the entity's [PVS(Potential Visibility Set)](https://developer.valvesoftware.com/wiki/PVS "PVS - Valve Developer Community") with the given value with the SetNW2* functions like <page>Entity:SetNW2String</page> and the value can be returned by using the GetNW2* functions like <page>Entity:GetNW2String</page>. <note> The value will only be updated clientside if the entity is or enters the client's [PVS(Potential Visibility Set)](https://developer.valvesoftware.com/wiki/PVS "PVS - Valve Developer Community"). The value will only be networked if it isn't the same as the current value and unlike SetNW* the value will only be networked once and not every 10 seconds. All NW2 values will be accessible clientside when the <page>GM:InitPostEntity</page> hook is called SetGlobal2* works internally like ```Entity(0):SetNW2*``` and because of this, values set with the SetGlobal2* functions can be accessed with ```Entity(0):GetNW2*``` All NW2Vars set on a Player are updated every 10 seconds because of [sv_playerforcedupdate](https://wiki.facepunch.com/gmod/Networking_Usage#svplayerforcedupdateissue) </note> <bug issue="5455">You should not use the NW2 System on entities that are based on a Lua Entity or else NW2Vars could get mixed up, updated multiple times or not be set.</bug> It also allows to set global values with the SetGlobal2* functions like <page>Global.SetGlobal2String</page> and the value can be returned by using the GetGlobal2* functions like <page>Global.GetGlobal2String</page>. All SetGlobal2* functions will update the value clientside, and it will ignore the PVS. Hello World Example with the NW2 system ```lua if SERVER then Entity( 1 ):SetNW2String( "Example", "Hello World" ) else Entity( 1 ):SetNW2VarProxy( "Example", function( _, _, _, value ) print( value ) end) end ``` or ```lua if SERVER then Entity( 1 ):SetNW2String( "Example", "Hello World" ) else hook.Add( "EntityNetworkedVarChanged", "Example", function( _, _, _, value ) print( value ) end) end ``` If you want to network a table with the NW2 system, you can use <page>util.TableToJSON</page> to make it into a string, and then you can send it with <page>Entity:SetNW2String</page> or <page>Global.SetGlobal2String</page> and return it with <page>Entity:GetNW2String</page> or <page>Global.GetGlobal2String</page> <note>The string returned by <page>util.TableToJSON</page> should not be bigger than 511 characters.</note> <example> <description>Networking a Table containing Hello World</description> <code> if SERVER then local table = { "Hello World" } SetGlobal2String( "Example", util.TableToJSON( table ) ) else PrintTable( util.JSONToTable( GetGlobal2String( "Example" ) ) ) end </code> <output> ```lua 1 = Hello World ``` </output> </example> ### Some additional information about the NW2 System If <page>Entity:SetPreventTransmit</page> is set to `true`, it will leave the client's PVS and NW2Vars won't be networked. The Entity won't enter the client's PVS again under any circumbstances until it has been set to false again. A NW2Var is networked as a `entmessage`(Entity Message). <validate> <page>Entity:NetworkVar</page> seems to use the NW2 System internally, because of that, they share the same limits. </validate> <page>GM:EntityNetworkedVarChanged</page> only works for the NW2 System <page>Entity:UpdateTransmitState</page> affects <page>Entity:NetworkVar</page> but not NW2Vars set with `SetNW2*` You can use the [EFL_IN_SKYBOX](https://wiki.facepunch.com/gmod/Enums/EFL) Engine Flag to force the Entity into the PVS of every client. (This won't work for the clients. If you want to add clients to the PVS, you'll need to use <page>Global.AddOriginToPVS</page>) <example> <description>Forcing the Entity to Enter the PVS</description> <code> local ent = Entity( 93 ) -- some Prop outside your PVS if SERVER then ent:SetNW2String( "Hello", "World" ) ent:AddEFlags( EFL_IN_SKYBOX ) else hook.Add( "EntityNetworkedVarChanged", "Example", print ) end </code> <output> ```lua Entity [93][prop_physics] Hello nil World ``` </output> </example> There is no official function like <page>Global.BuildNetworkedVarsTable</page> for the NW2 System, but you could use a function like this one. <example> <code> -- This is not the fastest way, and it can get slower when more entities exist, but you shouldn't call this function so often. function BuildNetworked2VarsTable() local vars = {} for _, ent in ipairs(ents.GetAll()) do for key, tbl in pairs(ent:GetNW2VarTable()) do if !tbl.value then continue end -- GetNW2VarTable can return keys with nil values. if !vars[ent] then -- we do this, because we only want to add entitys who have NW2 Vars. vars[ent] = {} end vars[ent][key] = tbl.value -- adds the NW2 Var. end end return vars end </code> </example> # Networking Limits ## umsg limits The <page>umsg</page> library has a 256 bytes limit per message. The bytes are used as follows: > 2 Bytes are used Internally > x Bytes are used for the umsg Name(1 Byte for each character.) > left Bytes are used by the actual umsg. <note> The umsg buffer for sending the data is not limited. Because of that, you can send as many umsg's until you run out of memory. If you run out of memory, your game will simply crash. </note> By default, you can network 1024 bytes of umsgs to a client in a single tick. If you need more than that to speed up something or just more capacity is needed, you can increase the `sv_usermessage_maxsize (default 1024bytes)` ConVar to the needed amount of bytes. --- ## net limits The <page>net</page> library has a 64kb (65535 bytes - 3 bytes used internally) limit per message. The library has an internal buffer that has roughly a 256kb(2048kbit) limit before it overflows, and if it overflows, it will cause clients that receive the net message to disconnect. So do **NOT** fill the buffer. It also has clienside a reliable stream which will overflow if too many net messages are queued and the total size of all net messages is over 256kb(2048bit). <example> <description>Creating a net message that uses the maximum size</description> <code> local string = "" for k=1, 65532 do string = string .. "a" end net.Start( "test" ) net.WriteString( string ) net.Broadcast() </code> <output> ```lua 65536 524288 ``` </output> </example> ## net bandwidth ### reliable channel the bandwidth for the reliable channel is roughly at 120kb/s but can vary for each client. The ping and the amount of time needed to process the net message plays a huge amount and can influence the bandwidth strongly because the net buffer could fill up because more net messages are received than processed, which can lead to the client being kicked because of a buffer overflow. ### unreliable channel the bandwidth seems to be unlimited for the unreliable channel and only seems to be influenced by the amount of time needed to send the net message. The net message won't actually be received most of the time because the buffer would be full, and it would just skip the net message. #### clientside bugs (unreliable channel) At somewhere around 12kb/s the net buffer seems to be overloaded, and you will be frozen in place because your client won't be able to receive any net message from the server while the buffer is overloaded, but you're still able to send net messages to the server. As soon as the buffer returns to a normal state, you will start to receive all reliable net messages that got delayed because the buffer overloaded. #### serverside bugs (unreliable channel) At somewhere around 12kb/s the net buffer seems to be overloaded, and the server will start to lag without any connection problems or packet loss. All inputs are getting delayed and some like jumping won't work right. The server will return to a normal state when the net buffer returns to a normal state. --- ## NW limits The NW system uses a stringtable that has 4095 slots and is used by all SetGlobal*, SetNW* functions and the <page>util.AddNetworkString</page> function. By default, 95 slots are used. Each new key will use a slot, so if you use the same key on all entities, it will only use 1 slot. The Maximum length for an NWVar Name is 49 characters. <warning> The NW System uses <page text="user messages">umsg</page> to network the Vars. Because of this, the maximum size of an NWVar can be 255 bytes. </warning> <example> <description>Returning the amount of used slots and the last key</description> <code> for k = 1, 4096 do if !util.NetworkIDToString( k ) then print( k - 1, util.NetworkIDToString( k - 1 ) ) break end end </code> <output> ```lua 95 ServerName ``` </output> </example> --- ## NW2 limits The NW2 system uses a separate stringtable that has 4095 slots, so it is not influenced by the NW stringtable. The NW2 stringtable is used by all SetNW2* and SetGlobal2* functions. By default, the stringtable is completely empty. Each new key will use a slot, so if you use the same key on all entities, it will only use 1 slot. Currently, there is no way of checking the usage of the NW2 string table. The maximum length for an NW2Var key is 1023 characters. (why can you network more data for a key that a value? (SetNW2String can only network 511 characters.)) If you need to network a string smaller than 1023 characters but bigger than 511 characters, see the example for <page>Entity:SetNW2String</page> # Networking Optimization ## sv_playerforcedupdate issue If you run a larger server, you maybe noticed that players are force updated every 10 seconds. This is because of `sv_playerforcedupdate (default 10)` which defines the amount of seconds to wait before updating a player again. It updates the player by adding it to the PVS for one tick and then removing it in the next. This is also the reason why NW2Vars are updated for players every 10 seconds (If they are out of sync). This issue can cause massive amounts of networking for the client, and It can cause short frame drops. If we were to set `sv_playerforcedupdate` to a number like `1000` and then change it back to `1`, this change would only apply after the next update. In this case after 1000 seconds If you set it to `0` all players are updated every frame! You can see an example of the networking spikes, I mean [here](https://i.imgur.com/Zfz6n1q.png) <example> <description> This is one of the ways to solve this Problem. This solution is not perfect because we add the entire position to the PVS instead of just the Player. We do it like this because currently there is no way to add a single entity to the PVS. </description> <code> -- This is the Clientside part. if CLIENT then local cooldown = 0 -- This event is called twice. Because of this, we add a delay so that don't request it twice. hook.Add( "InitPostEntity", "RequestFullPlayerUpdate", function() gameevent.Listen( "OnRequestFullUpdate" ) -- We do this clientside because this event is called after the Update has been received. hook.Add( "OnRequestFullUpdate", "RequestFullPlayerUpdate", function( data ) if data.userid != LocalPlayer():UserID() then return end -- We can receive events about other players, so we need to filter them. if cooldown > CurTime() then return end net.Start( "RequestFullPlayerUpdate" ) net.SendToServer() cooldown = CurTime() + 5 end) net.Start( "RequestFullPlayerUpdate" ) -- Just to be sure the client has everything. net.SendToServer() end) return end -- The Clientside part is above. The rest is serverside only. -- This returns all players that are inside the PVS. local function player_FindInPVS( viewPoint ) local plys = {} for _, ent in ipairs( ents.FindInPVS( viewPoint ) ) do if ent:IsPlayer() then table.insert( plys, ent ) end end return plys end -- This returns all players that are outside the PVS. local function player_FindOutsidePVS( viewPoint ) local plys = {} local pvs_plys = player_FindInPVS( viewPoint ) for _, ply in ipairs( player.GetAll() ) do if !pvs_plys[ ply ] then -- We check if the player is inside the PVS. If he is not inside the PVS, we add him to the Table. table.insert( plys, ply ) end end return plys end local query = {} local query_size = 0 local function RemovePlayer( query, id, ply ) query[ id ] = nil if #query == 0 then query[ ply ] = nil query_size = query_size - 1 if query_size == 0 then hook.Remove( "SetupPlayerVisibility", "Player_Query" ) -- We remove the hook if hes not needed. end end end local function SetupPlayerVisibility( ply ) local left_plys = query[ ply ] if !left_plys then return end -- Skip if no players are left. local id local next_ply for k, v in pairs( left_plys ) do -- ipairs breaks so we need to use pairs. id = k next_ply = v break end if next_ply:TestPVS( ply ) then -- We check if the Player is inside the PVS. If he is, we remove him from the list. RemovePlayer( left_plys, id, ply ) return end AddOriginToPVS( next_ply:GetPos() ) RemovePlayer( left_plys, id, ply ) --[[ If we have a crowded server where most of the players are in the same place, we can check if other players are also in the query. You can disable the code below if you only have a few players, or they all distributed across the map, but I don't recommend it. The code below saves a bunch of networking because players that are in the PVS of another player that has been networked are removed. ]] local pvs_plys = {} for _, pvs_ply in ipairs( player_FindInPVS( next_ply ) ) do -- We flip the table because this saves performance. pvs_plys[ pvs_ply ] = true end for key, left_ply in pairs( left_plys ) do if pvs_plys[ left_ply ] then RemovePlayer( left_plys, key, ply ) end end end util.AddNetworkString( "RequestFullPlayerUpdate" ) net.Receive( "RequestFullPlayerUpdate", function( _, ply ) query[ ply ] = player_FindOutsidePVS( ply ) -- We add a table containing all players that we want to add to the PVS if query_size == 0 then hook.Add( "SetupPlayerVisibility", "Player_Query", SetupPlayerVisibility ) -- We add the hook when it's needed. end query_size = query_size + 1 end ) </code> </example> # Networking Errors ## umsg errors  ```lua Error sending usermessage - too large ([name]) ``` This error is created serverside when you exceed the <page>umsg</page> limit of 256 bytes. Reduce the size of your umsg to solve this error. ---  ```lua Warning: Unhandled usermessage '[name]' ``` This error is created clientside when you forgot to use <page>usermessage.Hook</page> with the right key. <note>The <page>umsg</page> is deprecated, and you should use the <page>net</page> library instead.</note> <example> <description>How to properly use the umsg library</description> <code> if SERVER then local filter = RecipientFilter() filter:AddAllPlayers() umsg.Start( "Example" ) umsg.String( "Hello World" ) umsg.End() else usermessage.Hook( "Example", function( msg ) print( msg:ReadString() ) end) end </code> </example> ---  ```lua Warning: [number] global queued usermessages! ``` This Warning occurs when sending more than 5000 <page text="umsg's">umsg</page> in the same time. This warning can be completely ignored because it won't affect anything. This Warning can be fixed by sending less <page text="umsg's">umsg</page> or disturbing them over a timespan. --- ## net errors  ```lua [addon] Trying to send an overflowed net message! ``` This error is created serverside when you exceed the net limit of 64kb (65536 bytes). Reduce the size of your net message to solve this error. ---  <image src="https://i.imgur.com/D0UEQrB.png"/> This error is created clientside when you overflowed the <page>net</page> reliable buffer, which has a 256kb(2048kbit) limit, and it will cause a client or all clients to be to disconnect. To fix this error, you have to reduce the amount of net messages or the size of the net messages you send, so they won't overflow the net buffer. You could distribute the net messages over a small period, so the net buffer has enough time to send all net messages. You also can send unreliable net messages that won't kick a Client, but instead it will just ignore all unreliable net messages that couldn't fit in the buffer. <example> <description>Overflowing the reliable buffer while using unreliable net messages so the client won't be kicked.</description> <code> local string = "" for k = 1, 65532 do string = string .. "a" end util.AddNetworkString( "Example" ) for k = 1, 4 do net.Start( "Example", true ) net.WriteString( string ) net.Broadcast() end </code> <output> Instead of kicking the client, all unreliable net messages just won't be received and the developer error: ```lua Netchannel: failed reading message clc_GMod_ClientToServer from loopback. ``` will be created. </output> </example> ---  ```lua loopback:send reliable stream overflow ``` This Error is shown when you overflow the clientside net reliable stream. When this error occurs the client won't be able to send any net messages to the server and after a while the client will be kicked because the server thinks the client timed out. To fix this, reduce the amount of net messages you want to send to the server and distribute them over a small period, so the steam has enough time to sent everything. ---  ```lua [Addon] Warning! A net message ([name]) is already started! Discarding in favor of the new message! (function origin of the net message) ``` This error is created by the <page>net</page> library when in a previous net message an error occurred. This can be fixed by fixing the error that has been created in the net message before it. ---  ```lua Netchannel: failed reading message svc_GMod_ServerToClient from loopback. ``` This Warning is shown when you set the ```developer``` ConVar to 1 or higher and an unreliable net message is received, and it doesn't fit in the net buffer. This can be fixed by reducing the amount of net messages sent and to distribute them over a small period. ---  ```lua Netchannel: failed reading message clc_GMod_ClientToServer from loopback. ``` This Warning is shown when you set the ```developer``` ConVar to 1 or higher and an unreliable net message is received, and it doesn't fit in the net buffer. This can be fixed by reducing the amount of net messages sent and to distribute them over a small period. ---  ```lua Warning! Trying to net.Broadcast a message '[name]' with no players on server! ``` This Warning is shown when you set the ```developer``` ConVar to 1 or higher, and you try to broadcast a net message while the server is empty. This Warning can be completly Ignored because it won't affect anything. ---  ```lua AUTOREFRESH: Not adding [file here] to datatable, its too large! ([file size] vs 65536) Refusing to send autorefreshed Lua file [file here], its too large! ([file size] vs 65536 max) ``` This Error is created, when you try to Autorefresh a file that contains more than 65536 chacters and even after some compression is still bigger than 65536 bytes. To solve this error, you need to reduce the size of your File. --- ## NW errors  ```lua DLL_MessageEnd: Refusing to send user message NetworkedVar of 256 bytes to client, user message size limit is 255 bytes ``` This Error is created, when you try to network a <page text="NWString">Entity:SetNWString</page> in which the length of the key and value together is greater than 255 bytes. This Error will occur every 10 seconds from that point on, because the NW System renetworks all NW Vars every 10 seconds. To fix this error, you have to reduce the size of your NWVar name. ---  ```lua Too many NWVar names, could not add name [key] ``` This error is created when you exceed the NW2Var limit, which is currently at 4095 slots. Reduce the amount of NW2Vars or consider using the <page>net</page> library to solve this error. --- ## NW2 errors  ```lua Host_Error: SV_PackEntity: SendTable_Encode returned false (ent 1). ``` This error is created when you try to network too many NW2Vars at the same time. When this error occurs, it will close the server and on your game will crash when you try to start a new game without restarting gmod first. If you should ever get this error, you should reduce the amount of NW2Vars that you're trying to network at the same time ---  ```lua Warning: Table networkstring is full, can't add [key] ``` This error is created when you exceed the NWVar limit, which is currently at 4095 slots. Reduce the amount of NWVars or consider using the <page>net</page> library or the SetNW* functions to solve this error.