GameHub

GameHub handles the communication among iframes by having a HubClient in each iframe that needs to send or receive messages and a Hub at the top level of the DOM, that makes sure every HubClient can communicate with each other.

Keywords

Channel is the distinction between your HubClient and others who might want to send messages with the same topic as you. This could be the name of your department.

Group is the grouping of HubClients that should receive a given message, and can be set when creating a HubClient. All HubClients in a single gametab should have the same group. The group could for instance be the id of the gametab.

Topic is the sort of message you are sending or listening for.

Payload is the data you are sending, but could potentially be empty if your topic is enough to tell other HubClients that some event has happened.

Target is the group you want your message to be sent to, if it differs from your own.

Callback is the function you want to be run when receiving a message that you subscribe to.

Usage example

This example serves to improve understanding of especially the Channel and Group terms.

Imagine two small villages. Let's call them Waterdeep and Highgarden. Outside each village is a farm and inside each village is a shop which sells the crops the farm produces. Each village is its own Group. That means we in our example have a Group called Waterdeep and a Group called Highgarden. Inside each group we have a farm and a shop. Both of these are Channels. Thus looking at Highgarden we have a Group called Highgarden and in it we have two Channels; Farm and Shop. Farm produces (publishes) crops (messages) which are consumed (subscribed to) by the Shop. The Farm outside Highgardencan simply produce its crops (i.e. publish its messages) using the publish method. As the gamehub client is instanced using the Highgarden group only the shop in Highgarden(which also has a gamehub client instanced with the Highgardengroup) will be able to receive the crops (messages) from the Highgarden Farm.

Given the above example the Farm in Highgarden would need to create its gamehub client with the following options.

{
    "options": {
        "channel": "farm",
        "group":   "highgarden"
    }
}

While the Shop in Highgarden would create its gamehub client using these options.

{
    "options": {
        "channel": "shop",
        "group":   "highgarden"
    }
}

When the Highgarden Farm publishes messages it can do it using just the publish method.

{
    "topic":    "new_crops",
    "payload":  ["apple", "potato", "turnip"]
}

As the gamehub client of the Highgarden Farm has the Highgarden group only other gamehub clients with the Highgarden group will be able to receive messages from the Highgarden Farm. You could also say Highgarden forms a namespace for the messages sent from the Farm.

The Highgarden Shop can receive the messages from the Highgarden Farm by simply using the subscribeTo method.

{
    "channel":  "farm",
    "topic":    "new_crops",
    "callback": "<function>
}

Hub

For messages to be handled there needs to be a Hub in the top level of your DOM. You will not achieve anything by instantiating a hub if you are not in the top level. Additionally if more hubs are created on the top level it will result in several instances of the same message being passed around the system. As such the hub should be treated as a singleton.

HubClients

To send and receive messages instantiate a HubClient. You can provide it with an options object containing any of the described values below or you can let it default to channel: engage, group: group-{Uuid}. Unless you know what you are doing do NOT use the default value for channel. Note that the channel you are passing in represents your module/iframe and will be used by others to identify you. Thus if your iFrame contains the chat a channel name of chat could be appropriate. Also note you can not use the same channel name as anyone else in the same group.

{
    "options": {
        "channel": "string",
        "group":   "string"
    }
}

HubClients offers the following functions for subscribing to and publishing messages

SubscribeTo

Listen for messages with the given channel and topic and perform the code given in callback when a message is received. The channel parameter is the channel of the module/iFrame you want to subscribe to messages from.

{
    "channel":  "string",
    "topic":    "string",
    "callback": "function"
}

Publish

Publish the given payload to other clients in the same group that listens on the clients channel, for the given topic. The other clients will be able to subscribeTo your message if they know your topic and channel.

{
    "topic":    "string",
    "payload":  "object"
}

PublishTo

Publish the given payload to the clients in the target group that listens on the clients channel, for the given topic.

{
    "topic":    "string",
    "target":   "string",
    "payload":  "object"
}

Broadcast

Broadcasts the given payload to every client listening on the clients channel for the given topic in your group.

{
    "topic":    "string",
    "payload":  "object"
}

Internal communication

Don't worry too much about this if you are setting up or using the system.

Communication from the Hub

{
    "channel":  "string",
    "topic":    "string",
    "target":   "string",
    "payload":  "object",
    "sender":   "string",
    "fromHub":  "bool"
}

Communication from a client

{
    "channel":  "string",
    "topic":    "string",
    "target":   "string",
    "payload":  "object",
    "sender":   "string"
}

Getting detailed logging from a client

Messages can be filtered by a client for a variety of reasons. Perhaps you are not subscribing to the correct topic? Perhaps the message is sent to another channel than yours? To lessen confusion you can turn on verbose message logging by calling setVerboseLogging(true) on your client.