Select your preferred scripting language. All code snippets will be displayed in this language.
Thank you for helping us improve the quality of Unity Documentation. Although we cannot accept all submissions, we do read each suggested change from our users and will make updates where applicable.
CloseFor some reason your suggested change could not be submitted. Please <a>try again</a> in a few minutes. And thank you for taking the time to help us improve the quality of Unity Documentation.
CloseTest this machines network connection.
Two types of tests are performed depending on if the machine has a public IP address present or if it only has a private address (or addresses).
The public IP address test is primarily for when running a server as no tests are needed for clients with public addresses. In order
for the public IP test to succeed a server instance must be started. A test server will try to connect to the
IP and port of the local server and thus it is shown in the server is connectable. If not then a firewall is most likely
blocking the server port. A server instance needs to be running so that the test server has something to connect
to.
The other test is for checking NAT punchthrough capabilities. This is a valid test for both servers and clients
and can be performed without any prior setup. There are 4 types of NAT test results (see ConnectionTesterStatus): __Full Cone_, Address Restricted Cone, Port restricted and
Symmetric.
First two types offer full NAT punchthrough support and can connect to any type. Port restricted type cannot connect to or receive a connection from symmetric
type. Symmetric if worst and cannot connect to other symmetric types or port restricted type. The latter two are labelled
as offering limited NAT punchthrough support.
This function is asynchronous and might not return a valid result right away because the tests needs
some time to complete (1-2 seconds). After test completion the test result is only returned when the function is called again,
a full network test is not redone. That way it is safe to poll the function frequently. If another test is desired,
like if the network connection has been altered, then the forceTest
parameter should be passed as true.
The function returns a ConnectionTesterStatus enum.
var testStatus = "Testing network connection capabilities."; var testMessage = "Test in progress"; var shouldEnableNatMessage : String = ""; var doneTesting = false; var probingPublicIP = false; var serverPort = 9999; var connectionTestResult = ConnectionTesterStatus.Undetermined;
// Indicates if the useNat parameter be enabled when starting a server var useNat = false;
function OnGUI() { GUILayout.Label("Current Status: " + testStatus); GUILayout.Label("Test result : " + testMessage); GUILayout.Label(shouldEnableNatMessage); if (!doneTesting) TestConnection(); }
function TestConnection() { // Start/Poll the connection test, report the results in a label and // react to the results accordingly connectionTestResult = Network.TestConnection(); switch (connectionTestResult) { case ConnectionTesterStatus.Error: testMessage = "Problem determining NAT capabilities"; doneTesting = true; break;
case ConnectionTesterStatus.Undetermined: testMessage = "Undetermined NAT capabilities"; doneTesting = false; break;
case ConnectionTesterStatus.PublicIPIsConnectable: testMessage = "Directly connectable public IP address."; useNat = false; doneTesting = true; break;
// This case is a bit special as we now need to check if we can // circumvent the blocking by using NAT punchthrough case ConnectionTesterStatus.PublicIPPortBlocked: testMessage = "Non-connectable public IP address (port " + serverPort +" blocked), running a server is impossible."; useNat = false; // If no NAT punchthrough test has been performed on this public // IP, force a test if (!probingPublicIP) { connectionTestResult = Network.TestConnectionNAT(); probingPublicIP = true; testStatus = "Testing if blocked public IP can be circumvented"; timer = Time.time + 10; } // NAT punchthrough test was performed but we still get blocked else if (Time.time > timer) { probingPublicIP = false; // reset useNat = true; doneTesting = true; } break; case ConnectionTesterStatus.PublicIPNoServerStarted: testMessage = "Public IP address but server not initialized, "+ "it must be started to check server accessibility. Restart "+ "connection test when ready."; break;
case ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted: testMessage = "Limited NAT punchthrough capabilities. Cannot "+ "connect to all types of NAT servers. Running a server "+ "is ill advised as not everyone can connect."; useNat = true; doneTesting = true; break;
case ConnectionTesterStatus.LimitedNATPunchthroughSymmetric: testMessage = "Limited NAT punchthrough capabilities. Cannot "+ "connect to all types of NAT servers. Running a server "+ "is ill advised as not everyone can connect."; useNat = true; doneTesting = true; break;
case ConnectionTesterStatus.NATpunchthroughAddressRestrictedCone: case ConnectionTesterStatus.NATpunchthroughFullCone: testMessage = "NAT punchthrough capable. Can connect to all "+ "servers and receive connections from all clients. Enabling "+ "NAT punchthrough functionality."; useNat = true; doneTesting = true; break;
default: testMessage = "Error in test routine, got " + connectionTestResult; } if (doneTesting) { if (useNat) shouldEnableNatMessage = "When starting a server the NAT "+ "punchthrough feature should be enabled (useNat parameter)"; else shouldEnableNatMessage = "NAT punchthrough not needed"; testStatus = "Done testing"; } }]></code> </example> <description>If you know both server and client NAT types you could use the following function to determine if the client can connect to the server or not.</description> <example> <code lang="js"><![CDATA[ function CanConnectTo(type1: ConnectionTesterStatus, type2: ConnectionTesterStatus) : boolean { if (type1 == ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted && type2 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric) return false; else if (type1 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric && type2 == ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted) return false; else if (type1 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric && type2 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric) return false; return true; }
using UnityEngine; using System.Collections;
public class ExampleClass : MonoBehaviour { string testStatus = "Testing network connection capabilities."; string testMessage = "Test in progress"; string shouldEnableNatMessage = ""; bool doneTesting = false; bool probingPublicIP = false; int serverPort = 9999; bool useNat = false; float timer = 0.0f;
ConnectionTesterStatus connectionTestResult = ConnectionTesterStatus.Undetermined;
void OnGUI() { GUILayout.Label("Current Status: " + testStatus); GUILayout.Label("Test result : " + testMessage); GUILayout.Label(shouldEnableNatMessage);
if (!doneTesting) TestConnection(); }
void TestConnection() { // Start/Poll the connection test, report the results in a label and // react to the results accordingly connectionTestResult = Network.TestConnection(); switch (connectionTestResult) { case ConnectionTesterStatus.Error: testMessage = "Problem determining NAT capabilities"; doneTesting = true; break;
case ConnectionTesterStatus.Undetermined: testMessage = "Undetermined NAT capabilities"; doneTesting = false; break;
case ConnectionTesterStatus.PublicIPIsConnectable: testMessage = "Directly connectable public IP address."; useNat = false; doneTesting = true; break;
// This case is a bit special as we now need to check if we can // circumvent the blocking by using NAT punchthrough case ConnectionTesterStatus.PublicIPPortBlocked: testMessage = "Non-connectable public IP address (port " + serverPort + " blocked), running a server is impossible."; useNat = false; // If no NAT punchthrough test has been performed on this public // IP, force a test if (!probingPublicIP) { connectionTestResult = Network.TestConnectionNAT(); probingPublicIP = true; testStatus = "Testing if blocked public IP can be circumvented"; timer = Time.time + 10; } // NAT punchthrough test was performed but we still get blocked else if (Time.time > timer) { probingPublicIP = false; // reset useNat = true; doneTesting = true; } break;
case ConnectionTesterStatus.PublicIPNoServerStarted: testMessage = "Public IP address but server not initialized, " + "it must be started to check server accessibility. Restart " + "connection test when ready."; break;
case ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted: testMessage = "Limited NAT punchthrough capabilities. Cannot " + "connect to all types of NAT servers. Running a server " + "is ill advised as not everyone can connect."; useNat = true; doneTesting = true; break;
case ConnectionTesterStatus.LimitedNATPunchthroughSymmetric: testMessage = "Limited NAT punchthrough capabilities. Cannot " + "connect to all types of NAT servers. Running a server " + "is ill advised as not everyone can connect."; useNat = true; doneTesting = true; break;
case ConnectionTesterStatus.NATpunchthroughAddressRestrictedCone: case ConnectionTesterStatus.NATpunchthroughFullCone: testMessage = "NAT punchthrough capable. Can connect to all " + "servers and receive connections from all clients. Enabling " + "NAT punchthrough functionality."; useNat = true; doneTesting = true; break;
default: testMessage = "Error in test routine, got " + connectionTestResult; break; }
if (doneTesting) { if (useNat) shouldEnableNatMessage = "When starting a server the NAT " + "punchthrough feature should be enabled (useNat parameter)"; else shouldEnableNatMessage = "NAT punchthrough not needed"; testStatus = "Done testing"; } } }
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thanks for helping to make the Unity documentation better!