gfwleak/zhangyang-libzt
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated Unity OSX and iOS readmes

Browse Source
This commit is contained in:
Joseph Henry
2016-06-21 10:12:45 -07:00
parent 686c3d57fb
commit c50548a12c
3 changed files with 193 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/unity3d_ios_zt_sdk.md
View File

@@ -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();
}
}
```

124
docs/unity3d_osx_zt_sdk.md Normal file
View File

@@ -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.

117
docs/zt_llapi_unity.md
View File

@@ -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");
}
}
}
```