Docs

Thanks for checking out Gossip.

Before continuing, you should create an account or sign in.

Game Configuration

Once you have an account, visit your configuration page. This will let you create a game on Gossip. It will then show you your Client ID and Client Secret which will be used to authenticate against the Gossip network.

Channels

You also subscribe to the channels you want your game to pay attention to. Right now Gossip has the following channels:

  • gossip
  • testing

In addition to those listed above, you can subscribe to any valid channel name. This will make dynamically create channels as you subscribe to them. They will exist for anyone to connect to, but not show on the website until the admins approve them.

A valid channel name must be <=15 characters and letters only.

You will only recieve messages for channels you are subscribed to.

Server Support

The following servers/frameworks have built-in support or a library to import for Gossip support:

Connecting

Once you have your Client ID and Client Secret, you can start connecting to the Gossip network. Point your websocket client at:

wss://gossip.haus/socket

Once you are connected, you must send an authenticate message to authenticate your connection.

Expectations of a Connecting Game

If you are connecting to the Gossip network, please know that you connect under the following assumptions:

  1. Gossip will go down sometime while you are connected. Most likely for a new deploy. Make sure your game does not crash because of this.
  2. While Gossip is down, your app should transition channels to local only.
  3. Similarly, you should reconnect back to Gossip when it comes back online.
  4. You must support unicode at the server level. Several connected games allow unicode input so you may receive it at any time.

Core Events (channels)

Below is a list of events you can send or may receive from the socket.

authenticate

This event authorizes the connection and afterwards you will start to receive new broadcasts.

supports is required. This is an array of features the connecting game supports. It must contain at least channels. Extra unknown options will result in the socket being disconnected.

channels is optional. This is an array of channels you wish to subscribe to on start. See the list of channels for available channels you can subscribe to.

user_agent is optional but suggested. If present, this will show on the Games page.

{
  "event": "authenticate",
  "payload": {
    "client_id": "client id",
    "client_secret": "client secret",
    "supports": ["channels"],
    "channels": ["gossip"],
    "user_agent": "ExVenture 0.23.0"
  }
}

You will receive a response from this with a sucess or failure message.

{
  "event": "authenticate",
  "status": "success"
  "unicode": "✔️"
}

If you attempt to subscribe to bad channels, you may receive a failed subscribe message. See more below about valid channel names.


heartbeat

Once you are authenticated, the server will start sending heartbeat events.

{
  "event": "heartbeat",
}

When you receive a heartbeat, you must respond to it with a heartbeat of your own. This should include a list of your players that are online.

{
  "event": "heartbeat",
  "payload": {
    "players": ["player"]
  }
}

NOTE: If you do not respond to these heartbeats the socket will be closed after three failed beats.


channels/subscribe

Subscribe to a new channel on your currently connected socket.

{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b",
  "payload": {
    "channel": "gossip"
  }
}

On success, if a ref is included then you will get a response back confirming your message.

{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b"
}

You may receive a response to this as a failure, channel names are validated. Channel names must be <=15 characters and letters only.

{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b",
  "status": "failure",
  "error": "Could not subscribe to 'bad channel name'",
}

channels/unsubscribe

Unsubscribe to a channel you are subscribed to.

{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466",
  "payload": {
    "channel": "gossip"
  }
}

On success, if a ref is included then you will get a response back confirming your message.

{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466"
}

messages/broadcast

When a channel you are subscribed to receives a new message you will get a broadcast.

{
  "event": "messages/broadcast",
  "ref": "89036074-446f-41ab-b87a-44ef1f962f2e",
  "payload": {
    "channel": "gossip",
    "message": "Hello everyone!",
    "game": "ExVenture",
    "name": "Player"
  }
}

messages/new

To send a new message, use this event. channel must be a channel you are subscribed to. All of the fields in the payload are required.

You will not get a broadcast message back for messages you send.

{
  "event": "messages/new",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b",
  "payload": {
    "channel": "gossip",
    "name": "Player",
    "message": "Hello everyone!"
  }
}

On success, if a ref is included then you will get a response back confirming your message.

{
  "event": "messages/new",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b",
}

Player Events (players)

These events are related to the players support flag. Add this to your supports array when connecting.


players/sign-in

When a player signs into your game, send this message. It will broadcast to other games and also update Gossip's tracking of who is signed in.

You will not get a broadcast message back for messages you send.

{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f",
  "payload": {
    "name": "Player"
  }
}

On success, if a ref is included then you will get a response back confirming your message.

{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f"
}

While connected with the players flag, you may receive an update from another game. You may wish to broadcast to your local players that someone has come online in the network.

{
  "event": "players/sign-in",
  "payload": {
    "game": "ExVenture",
    "name": "Player"
  }
}

Note: you must still respond to heartbeats with your full list. Each beat fully replaces the list ensuring it keeps in sync. This is for between the beats and notifying connected games.


players/sign-out

When a player signs out of your game, send this message. It will broadcast to other games and also update Gossip's tracking of who is signed in.

You will not get a broadcast message back for messages you send.

{
  "event": "players/sign-out",
  "ref": "da4c5503-dd15-490a-9d0d-85e2c50b72de",
  "payload": {
    "name": "Player"
  }
}

On success, if a ref is included then you will get a response back confirming your message.

{
  "event": "players/sign-out",
  "ref": "da4c5503-dd15-490a-9d0d-85e2c50b72de"
}

While connected with the players flag, you may receive an update from another game. You may wish to broadcast to your local players that someone has gone offline in the network.

{
  "event": "players/sign-out",
  "payload": {
    "game": "ExVenture",
    "name": "Player"
  }
}

Note: you must still respond to heartbeats with your full list. Each beat fully replaces the list ensuring it keeps in sync. This is for between the beats and notifying connected games.

Socket Error Code

4000
Authentication failed
4001
Heartbeat failure