Skip to content

Basics

Jump to bottom
Ian edited this page Dec 10, 2019 · 10 revisions

ScapeNet can be used entirely independently, but is built with Unity in mind.

Setting up a connection with ScapeNet is easy, but there are a few different approaches, which depend on what you are creating. ScapeNet uses something called 'Networkers', these are basically, the Lidgren side of the library. They interact directly with Lidgren to sort all packets that are received and send the appropriate ones where they need to go. In the future you will be able to customise these easily with no, or very little Lidgren knowledge.

Four Networkers are included by default, there are two for the client, and two for the server:

  • Networker_Client
  • Networker_Client_Unity
  • Networker_Server
  • Networker_Server_Unity

Each of these 'Networkers' support the custom packet system at the heart of ScapeNet, but the '_Unity' variants provide the player and object system, providing each player and object with unique id's, and support for a number of features including: updating a new client on connection (sending over existing objects and their current position), object instantiation, object position and rotation sync, as well as disconnect, and object deletion support. Before using ScapeNet, the desired Networker pair must be selected based on what you would like from ScapeNet. Look at the needs below and choose what you need.

_Unity Variants - Need for the player and object system for automatic syncing of objects positions or rotations.

Standard Variant (eg without _Unity) - Only want the ScapeNet packet system without any object syncing, or if you want to develop your own syncing system based on ScapeNet.

The following code is specific to the Networker_Unity variants, however the code is exactly the same for the standard variants, but with the _Unity parts removed.

Server

Let's open a server:

Networker_Server_Unity server = new Networker_Server_Unity();
server.Setup("NetworkName", 7777);
server.HostServer(100, 10, "approvalcode");

This is fairly straight forward. We make a new instance of the Networker_Server_Unity class. We run the setup method, and provide a name for the network as well as a port, in this case, '7777'. Once setup has been ran, the object stores all of the configuration data. Next is the host server method, to which we provide the following parameters (timeout, max_connections, approval_code). Once the method has been ran the server is then online, and relies on the following method being ran:

Now we need to poll the server for packets (ran in while loop, or Unity's update method):

server.Update();

Client

Let's now start a client (this can be ran in the same file as the server, but the server must be ran first):

Networker_Client_Unity client = new Networker_Client_Unity();
client.Setup("NetworkName");
client.StartClient("localhost", 7777, "approvalcode");

This is also straight forward. We make a new instance of the Networker_Client_Unity class. We run the setup method, and provide a name for the network. Once setup has been ran, the object stores all of the configuration data. Next is the start client method, to which we provide the following parameters (ip, port, approval_code). Once the method has been ran the client is then online, and relies on the following method being ran:

Now we need to poll the client for packets (ran in while loop, or Unity's update method):

client.Update();

The client and server are now connected!

Sending & Receiving Packets

Now we will proceed to sending packets, both from the server to the client, and the client to the server. This will follow using a default packet type, known as the TestPacket, its structure allows it to hold a single string.

First, there are a number of default packet types (we will cover how to create new ones in the following page), they are as follows:

  • Test Packet
  • Connection Packet
  • Instantiate Packet
  • Delete Packet
  • PositionRotation Packet
  • OnConnect Packet

Each of the above packets are internally used by the library, and so should mostly be ignored (but they can be manually sent if needed, or desired). There are no 'receivers' for a test packet by default on either the client or server, but it's type has already been defined and been registered internally.

Sending

Let's send a test packet to the server from the client:

TestPacket packet = new TestPacket("Test");
packet.testString = "I am the client!";
client.SendPacketToServer(packet);

If you wanted to do the reverse (eg, server to client) the following would be written:

TestPacket packet = new TestPacket("Test");
packet.testString = "I am the server!";
server.SendPacketToAll(packet, -1);

All packets take in a string within their respective constructors. This string is the packet identifier, and it is used to name the packet. This name is used when receiving packets. Notice the (-1) specified when sending a packet from the server to a client, this is the player id associated with the sender (Only used in the Unity variants), a value of -1 is used when there is no forwarding from an already received connection. Let's see how to retrieve the data within the packets once they have been received.

Receiving

In order to retrieve the information from our received packet, the following must be written:

client.OnReceive("Test", received => {
   PacketData<TestPacket> data = new PacketData<TestPacket>(received);
   Console.WriteLine("We have received some data from the server: " + data.packet.testString);
       
   return false;
});

The following can be written on the server:

server.OnReceive("Test", received => {
    PacketData<TestPacket> data = new PacketData<TestPacket>(received);
    Console.WriteLine("We have received some data from the client: " + data.packet.testString);
       
    return false;
});

The values returned bears little weight at the moment. However, a value of true returned on the server, will cause the packet to be sent to all connections. (simply an echo, if packets are sent this way, then the modifications done within the OnReceive method will not be sent). This can be useful for only wanting to look at a received packet's information, while not modifying it.

Notice the use of the string "Test" here. This string is known as the packet identifier and denotes what the client/server will look when used in OnReceive.

E.g... You could create another test packet with the identifier of "Test2". The receive methods would also need to be given the string "Test2" or they would not be called.

Clone this wiki locally