Narwhal:Networking
From GMod Wiki
| Go to: Narwhal |
 | This page needs to be edited as it contains information that is unclear or incorrect. Improvement can be discussed on the talk page. Find more pages that need work here. Details: None given. |
Contents |
Overview
Narwhal has a custom networking system which is meant to lighten the load of network-heavy gamemodes. If you don't feel like using it, that's fine. Narwhal's networking doesn't do any frequent processes in the background so there's no need to worry about it bogging you down.
Note - If your gamemode works fine with the default networking in GMod or you are effectively using usermessages, there's no need to switch to Narwhal's networking.
About
About GMod's Networking
GMod's default networking is not bad, it's just meant to be used in moderation. In GMod, networked variables are evaluated frequently to see if they've changed. If they have changed, they are sent to the client for synchronization. When you have 50 networked variables set on each player, you are creating a recipe for disaster. Each of those variables is getting looped and checked for changes multiple times every second, and that can be taxing on the server.
About Narwhal's Networking
Narwhal's networking system is really more like glorified usermessages. Unlike GMod's networking, it synchronizes variables on the client on a per-change, and rarely on a per-request basis. This means it will only send the variables from server to client when one of two things happens:
- The server calls one of the data sending utilities.
- The client directly requests the data from the server.
Instead of keeping a list of variables to frequently check for change, Narwhal keeps a list of variables as a cache on the server, and sends them whenever they change. When the client receives the variable, it gets stored in a clientside cache for fetching. The client has the ability to request variables from the server, but this is not meant for frequent use.
Supported Types
Narwhal's networking supports the following data types:
However, there are some distinctions to be made.
- All numbers in Lua are floats. The only difference between Integers and Floats in this context is that in the case that a float is sent as an integer, the decimal points will be chopped off with math.floor.
- Colors are actually tables, but it's more efficient to send a few chars than it is to send a serialized table. That's where custom network configurations come into play.
Functions
Here's a list of functions that can be used to control Narwhal's Networking:
- GM.LoadNetworkConfigurations
- NARWHAL.AddValidNetworkType
- NARWHAL.GetNetworkData
- NARWHAL.SendNetworkedVariable
- NARWHAL.FetchNetworkedVariable
- NARWHAL.RemoveNetworkedVariables
- NARWHAL.ResendNetworkedVariable
- NARWHAL.SendCachedVariable
- NARWHAL.GetSubscribedVars
Sending and Fetching
SendNetworkedVar
Do not use the NARWHAL.SendNetworkedVariable method directly. Use the Entity methods for each individual type.
FetchNetworkedVar
Do not use the NARWHAL.FetchNetworkedVariable method directly. Use the Entity methods for each individual type.
Network Filters
What is a Network Filter?
When sending a networked variable with Narwhal, there is an option Filter argument. These allow you to control who recieves and has permission to fetch the variable once it has been created. These do not use the RecipientFilter object. You have several options of how to define your filters.
Filter Types
- Player - When using a single player entity as the filter they will be the only one to recieve the var.
- Table - This needs to be a table of players. If this is a table that is determined by specific parrameters, it's better to use a Filter function which is explained next.
- Function - This is the preferable Filter type. This function needs to return a table of players. The advantage of using a Filter Function is that it will be called whenever an individual recipient's Network Subscriptions change. For instance, the default Filter is player.GetAll, but it's passed as a function instead of a table so that whenever new players join, they won't be left out of the filter when they request it.
- Enum - These represent specific functions. For instance, NARWHAL_NW_ALL represents player.GetAll, NARWHAL_NW_MYTEAM represents all players on the team of the player who is setting the var. Some of the enumerations make use of the FilterArgs(...) which proceed the Filter argument. NARWHAL_NW_TEAM is the team.GetPlayers function, so you'd want to proceed that with a team number to pass as an argument for that function.
Notes
- The FilterArgs(...) argument is only valid when you have a Filter Function or Filter Enumeration that uses arguments as your filter.
- The filter will remain the same after setting it the first time until you send it with a different one.
Custom Network Configurations
What is a Network Configuration?
A network configuration is a set of information that defines the actions to be taken when sending and fetching an abstract datatype. Most datatypes are already defined in Narwhal for you. Stuff like strings, numbers, tables, booleans, and more have a network configuration. A good example of an abstract datatype in Garry's Mod would be Colors. Colors are just tables, but they have a specific set of values that are always interpreted the same way. You could always send a serialized table with umsg.String, but that's not very efficient. Since we know it will always hold 'r', 'g', 'b', and 'a' as specific values, we can easily send them with umsg.Char, which is much more efficient than converting a table into a string.
Chances are that the average developer will have no use for this, but sometimes a gamemode will have very specific sets of values for each player which need to be synchronized on the client frequently. Lets say every player has three values that the developer wants to send to the client frequently. The developer could put each of the values in a table with specific indexes that would be easy to separate in a usermessage. By defining a network configuration for it, the developer would only need to call one method to send all three values. Instead of sending a networked string, integer, and boolean, you could send a table that holds those three values in one networking utility. You could of course use Entity.SendNetworkedTable, but it may not be as efficient as you doing a umsg.String, umsg.Short, and umsg.Bool.
LoadNetworkConfigurations
GM.LoadNetworkConfigurations is an empty function called internally to load the user's custom network configurations. To add your own network configurations, call the NARWHAL.AddValidNetworkType method from inside this function.
AddValidNetworkType
See NARWHAL.AddValidNetworkType for more information.
Other Networking Utilities
GetNetworkData
RemoveNetworkedVariables
ResendNetworkedVariable
SendCachedVariable
GetSubscribedVars
And that's all there is to it.
