diff --git a/docs/unity3d_ios_zt_sdk.md b/docs/unity3d_ios_zt_sdk.md index ee2e772..246378e 100644 --- a/docs/unity3d_ios_zt_sdk.md +++ b/docs/unity3d_ios_zt_sdk.md @@ -1,84 +1,94 @@ -Unity3D + ZeroTier SDK +Unity3D iOS + ZeroTier SDK ==== Welcome! We want your Unity apps to talk *directly* over a flat, secure, no-config virtual network without sending everything into the "cloud". Thus, we introduce the ZeroTier-Unity3D integration! -Our implementation currently intends to be the bare minimum required to get your Unity application to talk over ZeroTier virtual networks. As a result, we've created an API that is very similar to the built-in Unity LLAPI. It's possible that higher-level functionality could be added in the future. +Our implementation currently intends to be the bare minimum required to get your Unity application to talk over ZeroTier virtual networks. As a result, we've created an API that is very similar to the classic BSD-style sockets API. With this basic API it is possible to construct more abstracted network layers much like Unity's LLAPI and HLAPI. + +*** +## API + +- `Join(nwid)`: Joins a ZeroTier virtual network +- `Leave(nwid)`: Leaves a ZeroTier virtual network +- `Socket(family, type, protocol)`: Creates a ZeroTier-administered socket +- `Bind(fd, addr, port)`: Binds to that socket on the address and port given +- `Listen(fd, backlog)`: Puts a socket into a listening state +- `Accept(fd)`: Accepts an incoming connection +- `Connect(fd, addr, port)`: Connects to an endpoint associated with the given `fd` +- `Write(fd, buf, len)`: Sends data to the endpoint associated with the given `fd` +- `Read(fd, buf, len)`: Receives data from an endpoint associated with the given `fd` +- `CLose(fd)`: Closes a connection with an endpoint *** ## Adding ZeroTier to your Unity app **Step 1: Create virtual ZeroTier [virtual network](https://my.zerotier.com/)** -**Step 2: Add plugin** - - Create a folder called `Plugins` in `Assets` - - Place `ZeroTierUnity.bundle` in that folder +**Step 2: Add plugin to Unity project** + - Create folder `Assets/Plugins` + - Place `ZeroTierSDK_Unity3D_iOS.bundle` in folder -**Step 3: Add script to some `GameObject`** - - Drag our `ZeroTier.cs` native plugin wrapper onto any `GameObject` +**Step 3: Include wrapper class source** + - Drag `ZeroTierNetworkInterface.cs` into your `Assets` folder. +**Step 4: Create and use a `ZeroTierNetworkInterface` object** + - See examples below for how to use it! *** -## Examples - -Calling `ZeroTier.Init()` will start the network service in a separate thread. You can check if the service is running by checking `ZeroTier.IsRunning()`. Then, connecting and sending data to another endpoint would look something like the following: +## Server example ``` -public void zt_sample_network_test_thread() +public class Example { - // Prepare sample data buffer - byte[] buffer = new byte[1024]; - Stream stream = new MemoryStream(buffer); - BinaryFormatter f = new BinaryFormatter(); - f.Serialize ( stream , "Welcome to the machine! (from Unity3D)" ); + public ZeroTierNetworkInterface zt; - // Connect and send - int error; - Connect (0, "192.168.0.6", 8887, out error); - Send(connfd,buffer,0, out error); + public void example_server() + { + Thread connectThread = new Thread(() => { + // Create ZeroTier-administered socket + int sock = zt.Socket ((int)AddressFamily.InterNetwork, (int)SocketType.Stream, (int)ProtocolType.Unspecified); + zt.Bind(sock, "0.0.0.0", 8000); + zt.Listen(sock, 1); + + // Accept() client connection + int accept_sock = -1; + while(accept_res < 0) { + accept_sock = zt.Accept(sock); + } + + // Read data from client + char[] msg = new char[1024]; + int bytes_read = 0; + while(bytes_read >= 0) { + bytes_read = zt.Read(accept_sock, ref msg, 80); + string msgstr = new string(msg); + Debug.Log("MSG (" + bytes_read + "):" + msgstr); + } + }); + connectThread.IsBackground = true; + connectThread.Start(); + } } ``` -Finally, when you're done running the service you can call `ZeroTier.Terminate()` - -*** -## API - -The API is designed to resemble the Unity LLAPI, so you'll see a few familiar functions but with a slight twist. - -- `Join(nwid)`: Joins a ZeroTier virtual network -- `Leave(nwid)`: Leaves a ZeroTier virtual network -- `AddHost(port)`: Creates a socket, and binds to that socket on the address and port given -- `Connect(fd, ip_address, port, out error)`: Connects to an endpoint associated with the given `fd` -- `Send(fd, buf, pos, out error)`: Sends data to the endpoint associated with the given `fd` -- `Recv(fd, buf, out error)`: Receives data from an endpoint associated with the given `fd` -- `Disconnect(fd)`: Closes a connection with an endpoint - -*** -## Design and structure of the ZeroTier Unity OSX Bundle - -XCode: -New XCode project -Select Cocoa bundle as target -Add C linkages to external functions -Build as 64bit (not universal) - -Unity: -Select x86_64 build target in `Build Settings` -In new C# script asset: - -``` -[DllImport ("ZeroTierUnity")] -private static extern int unity_start_service (); +## Client example ``` +public class Example +{ + public ZeroTierNetworkInterface zt; -Add asset to GameObject -Start ZT service - -*** -## Future Roadmap -With the ZeroTier sockets API in place, higher-level functionality such as lobbies, chat, and object synchronization could easily be built on top. - - + public void example_client() + { + Thread connectThread = new Thread(() => { + // Create ZeroTier-administered socket + int sock = zt.Socket ((int)AddressFamily.InterNetwork, (int)SocketType.Stream, (int)ProtocolType.Unspecified); + zt.Connect (sock, "0.0.0.0",8000); + zt.Write(sock, "Welcome to the machine!", 24); + }); + connectThread.IsBackground = true; + connectThread.Start(); + } +} +``` \ No newline at end of file diff --git a/docs/unity3d_osx_zt_sdk.md b/docs/unity3d_osx_zt_sdk.md new file mode 100644 index 0000000..bf0f11e --- /dev/null +++ b/docs/unity3d_osx_zt_sdk.md @@ -0,0 +1,124 @@ +Unity3D OSX + ZeroTier SDK +==== + +Welcome! + +We want your Unity apps to talk *directly* over a flat, secure, no-config virtual network without sending everything into the "cloud". Thus, we introduce the ZeroTier-Unity3D integration! + +Our implementation currently intends to be the bare minimum required to get your Unity application to talk over ZeroTier virtual networks. As a result, we've created an API that is very similar to the classic BSD-style sockets API. With this basic API it is possible to construct more abstracted network layers much like Unity's LLAPI and HLAPI. + +*** +## API + +- `Join(nwid)`: Joins a ZeroTier virtual network +- `Leave(nwid)`: Leaves a ZeroTier virtual network +- `Socket(family, type, protocol)`: Creates a ZeroTier-administered socket +- `Bind(fd, addr, port)`: Binds to that socket on the address and port given +- `Listen(fd, backlog)`: Puts a socket into a listening state +- `Accept(fd)`: Accepts an incoming connection +- `Connect(fd, addr, port)`: Connects to an endpoint associated with the given `fd` +- `Write(fd, buf, len)`: Sends data to the endpoint associated with the given `fd` +- `Read(fd, buf, len)`: Receives data from an endpoint associated with the given `fd` +- `CLose(fd)`: Closes a connection with an endpoint + +*** +## Adding ZeroTier to your Unity app + +**Step 1: Create virtual ZeroTier [virtual network](https://my.zerotier.com/)** + +**Step 2: Add plugin to Unity project** + - Create folder `Assets/Plugins` + - Place `ZeroTierSDK_Unity3D_OSX.bundle` in folder + +**Step 3: Include wrapper class source** + - Drag `ZeroTierNetworkInterface.cs` into your `Assets` folder. + +**Step 4: Create and use a `ZeroTierNetworkInterface` object** + - See examples below for how to use it! + +*** +## Examples + +Start by creating a `ZeroTierNetworkInterface` object and calling +Calling `ZeroTier.Init()` will start the network service in a separate thread. You can check if the service is running by checking `ZeroTier.IsRunning()`. Then, connecting and sending data to another endpoint would look something like the following: +## Using ZeroTier Sockets API +### Server example +``` +public class Example +{ + public ZeroTierNetworkInterface zt; + + public void example_server() + { + Thread connectThread = new Thread(() => { + // Create ZeroTier-administered socket + int sock = zt.Socket ((int)AddressFamily.InterNetwork, (int)SocketType.Stream, (int)ProtocolType.Unspecified); + zt.Bind(sock, "0.0.0.0", 8000); + zt.Listen(sock, 1); + + // Accept() client connection + int accept_sock = -1; + while(accept_res < 0) { + accept_sock = zt.Accept(sock); + } + + // Read data from client + char[] msg = new char[1024]; + int bytes_read = 0; + while(bytes_read >= 0) { + bytes_read = zt.Read(accept_sock, ref msg, 80); + string msgstr = new string(msg); + Debug.Log("MSG (" + bytes_read + "):" + msgstr); + } + }); + connectThread.IsBackground = true; + connectThread.Start(); + } +} +``` + +### Client example +``` +public class Example +{ + public ZeroTierNetworkInterface zt; + + public void example_client() + { + Thread connectThread = new Thread(() => { + // Create ZeroTier-administered socket + int sock = zt.Socket ((int)AddressFamily.InterNetwork, (int)SocketType.Stream, (int)ProtocolType.Unspecified); + zt.Connect (sock, "0.0.0.0",8000); + zt.Write(sock, "Welcome to the machine!", 24); + }); + connectThread.IsBackground = true; + connectThread.Start(); + } +} +``` +*** +## Design and structure of the ZeroTier Unity OSX Bundle + +XCode: +New XCode project +Select Cocoa bundle as target +Add C linkages to external functions +Build as 64bit (not universal) + +Unity: +Select x86_64 build target in `Build Settings` +In new C# script asset: + +``` +[DllImport ("ZeroTierUnity")] +private static extern int unity_start_service (); +``` + +Add asset to GameObject +Start ZT service + +*** +## Future Roadmap +With the ZeroTier sockets API in place, higher-level functionality such as lobbies, chat, and object synchronization could easily be built on top. + + diff --git a/docs/zt_llapi_unity.md b/docs/zt_llapi_unity.md deleted file mode 100644 index 5c5a677..0000000 --- a/docs/zt_llapi_unity.md +++ /dev/null @@ -1,117 +0,0 @@ -ZeroTier Unity LLAPI -==== - -We've tried to replicate the behavior of the Unity3D LLAPI to make using ZeroTier as easy as possible. All you need to do is add the `ZeroTierSDK_Unity3D_YOUR-PLATFORM` library to the `assets/plugins` folder of your project and start using the `ZeroTierNetworkInterface`: - - -To start things off, go check out [ZeroTierSockets_Demo.cs](). Here are some examples of how to use the `ZeroTierNetworkInterface`: - -## Using ZeroTier Sockets API -### Server example -``` -Thread connectThread = new Thread(() => { - // Create ZeroTier-administered socket - int sock = zt.Socket ((int)AddressFamily.InterNetwork, (int)SocketType.Stream, (int)ProtocolType.Unspecified); - // Bind() - zt.Bind(sock, "0.0.0.0", 8000); - - // Listen() - zt.Listen(sock, 1); - - // Accept() loop - int accept_sock = -1; - while(accept_res < 0) { - accept_sock = zt.Accept(sock); - } - - char[] msg = new char[1024]; - int bytes_read = 0; - while(bytes_read >= 0) { - bytes_read = zt.Read(accept_sock, ref msg, 80); - string msgstr = new string(msg); - Debug.Log("MSG (" + bytes_read + "):" + msgstr); - } -}); -connectThread.IsBackground = true; -connectThread.Start(); -``` - -### Client example - -``` -Thread connectThread = new Thread(() => { - // Create ZeroTier-administered socket - int sock = zt.Socket ((int)AddressFamily.InterNetwork, (int)SocketType.Stream, (int)ProtocolType.Unspecified); - zt.Connect (sock, "0.0.0.0",8000); - zt.Write(sock, "Welcome to the machine!", 24); -}); -connectThread.IsBackground = true; -connectThread.Start(); -``` - - - -*** -## ~~Using the ZeroTier Low-level API (LLAPI)~~ -### Creating a host and receiving data - -``` -public class MyObject -{ - private ZeroTierNetworkInterface zt; - - void Start() - { - zt = new ZeroTierNetworkInterface("/Users/Bob/UnityGame/nc_8c493f5bef1747a6"); - zt.AddHost(8888); - } - - void Update() - { - int hostId; - int connectionId; - int channelId; - byte[] buffer; - int bufferSize; - int receivedSize; - byte error; - - NetworkEventType ne = zt.Receive(out hostId, out connectionId, out channelId, buffer, bufferSize, out receivedSize, out error); - - switch(ne) - { - case NetworkEventType.ConnectEvent: - Debug.Log("Client connected!"); - break; - case NetworkEventType.DataEvent: - Debug.Log("Received data from client!"); - } - } - -} -``` - -### Connecting to a server and sending a message - -``` -public class MyObject -{ - private ZeroTierNetworkInterface zt; - - void Start() - { - zt = new ZeroTierNetworkInterface("/Users/Bob/UnityGame/nc_8c493f5bef1747a6"); - - byte error; - int conn_id = zt.Connect(0, "192.168.0.50", "8080", out error); - - if(conn_id) { - zt.Send(conn_id, "Welcome to the machine!", 24, error); - } - else { - Debug.Log("Unable to connect to host"); - } - - } -} -``` \ No newline at end of file