The signal server is for communicating with other player's screens with small amounts of data. If you need to move a lot of information or stream data to a peer, use the signal server to setup an rtc connection and send it directly to them instead of through the signal server.
## First steps
To begin, your screen should wait for the signal-ready event.
This is emitted after connecting to a server and recieving a packet with the necessary information to use the signal server
```
dew.on("signal-ready", function (info) {
//Your client has now been assigned a password to connect to the signal server with
//info.data.server and info.data.password are needed
});
```
If you do not listen for the signal-ready event you can also retrieve this information using the server.websocketinfo command
This is useful for debugging since you can refresh the screen instead of needing to disconnect from the server and reconnecting.
*`server` - The server to connect to in the format ip:port
*`password` - Used for authenticating with the signal server
## Connecting to the signal server
Connection is done with a websocket and a subprotocol that is unique to your screen.
Your websocket should implement these functions at the time of creation
* 'onmessage' - For communication with other peers as well as possible disconnect reasons
* 'onopen' - So we can send our password at the first chance
* 'onclose' - For cleanup after the player leaves the server
```
var MyWebSocket = new WebSocket("ws://" + info.server, "MySubprotocol");
MyWebSocket.onopen = function(){
MyWebSocket.send(info.password);
}
MyWebSocket.onmessage = function(msg){
if(msg.data == "try again later"){} // The client was not been fully established and should wait a moment before sending the password again
else if(msg.data == "bad password"){} // Your password was incorrect
else{
//parse messages from other players
}
}
MyWebSocket.onclose = function(){
//We should do any cleanup that needs to happen, here.
}
```
The first message sent after connecting should be your password.
```
dew.on("signal-ready", function (info) {
var MyWebSocket = new WebSocket("ws://" + info.data.server, "MySubprotocol");
MyWebSocket.onopen = function(){
MyWebSocket.send(info.data.password);
}
});
```
Once you have sent your password, you will be free to submit messages to the signal server.
## Subprotocol
**The subprotocol is important.** Only peers that implement the same subprotocol when connecting to the signal server will be able to communicate with each other.
This is defined in the websocket's constructor.
```
var MyWebSocket = new WebSocket("ws://" + info.server, "MySubprotocol");
```
With the above snippet, only other websockets that use the subprotocol `MySubprotocol` will be able to receive messages from this socket.
# Talking to other screens
## Sending data
The signal server requires that all data sent has either of the below objects in json format
*`broadcast` - The data sent will be sent to all connected peers on the same subbprotocol
*`sendTo` - The data sent will only be sent to the peer specific
An example of sending a broadcast
```
MyWebSocket.send(JSON.stringify({
'broadcast': 'This is a message that other peers will see',
'extraData': 'We can send other things as long as broadcast or sendTo is used'
}));
```
Sending data to a specific peer is similar but uses the player's displayname + uid in the format name|uid attached to the sendTo object
```
MyWebSocket.send(JSON.stringify({
'sendTo': 'Maximumgame|8ff4e9111f9089c2',
'extraData': 'We can send other things as long as broadcast or sendTo is used'
}));
```
## Receiving data
When receiving data, the signal server will attach a peer's uid with their data automatically
```
MyWebSocket.onmessage = function(msg){
var data = JSON.parse(msg.data);
console.log(data.uid); // Maximumgame|8ff4e9111f9089c2 - Automatically created by the signal server
}
```
With this, your screen can uniquely identify where a message came from
### Signal server specific events
*`leave` - emitted when a player leaves or the socket disconnects. The leave object only contains a string of the uid of the player that has left. Similar to the uid object sent with other messages.
## Blacklist
The signal server will reject your message if anything below exists in the json sent
*`uid` - The server will create this for you. There is no need to attach your own.
*`leave` - The server will generate this message for you when your socket disconnects or the player leaves the game.
## Example
An implementation of a screen sending `Hello world!` when joining a server and a client responding with `Hi there!`
```
var MyWebSocket = null;
$(document).ready(function () {
dew.on("signal-ready", function (info) {
MyWebSocket = new WebSocket("ws://" + info.data.server, "HelloWorldExample");
MyWebSocket.onmessage = ParseMessage;
MyWebSocket.onopen = function(){
MyWebSocket.send(info.data.password); //send does not block so we need to wait a moment before sending our broadcast
