Hello, Hello

Pretty soon after you’ve sent the ack there should follow a roomHello. This is because the Mediator will normally only connect to your Room if someone tries to enter it. Thus, you see the ack, followed by the roomHello. The protocol doesn’t require this however, so try not to be dependent upon it. The only requirement here is that when the Mediator opens the websocket to you, that you respond with the ack. The Mediator could decide at that point to close the connection, or send any other valid packet (we’ll see some likely candidates in a bit).

roomHello,<roomId>,{
    "username": "username",
    "userId": "<userId>",
    "version": 1|2
}

The roomHello packet will arrive with your roomId as the recipient, and with the username & userId of the connecting user, along with the version Game On has selected to talk with you, this will be a version from the array you supplied in the ack.

You don’t have to send any response to a roomHello packet, it is information to tell you a user has joined your room. However, it is courteous to reply to a roomHello with a location response. We’ll cover that in a mo'.

Goodbye, Goodbye

As you might expect, if you get a roomHello when a player enters you room, you’ll also get a roomGoodbye when they leave. The goodbye packet is somewhat simpler, because it doesn’t have to do dual duty carrying information relating to the version Game On is using to talk to the room.

roomGoodbye,<roomId>,{
    "username": "username",
    "userId": "<userId>"
}

roomGoodbye is only sent when a player actively leaves the room via a /go command that switches the player location.

You don’t have to send any response to a roomGoodbye packet, it is information to tell you a user has left your room.

Wakey Wakey!!

What if a player falls asleep while in your room, or gets distracted by a YouTube video of Cats?

Arguably they have never left your room, but Game On knows they are no longer active, and may have suspended their session.

If you have claimed to support protocol version 2 (as suggested) in your ack, then there are 2 additional messages you can recieve, which will give you status updates on players that are 'in' your room: roomPart and `roomJoin.

roomPart,<roomId>,{
    "username": "username",
    "userId": "<userId>",
}
roomJoin,<roomId>,{
    "username": "username",
    "userId": "<userId>",
    "version": 2
}

You don’t have to send any response to these packets. Again they provide information to the room as players come and go, or become inactive / active. You will only recieve these messages for players that you have receieved a roomHello for (on socket connection). You should continue to see them until you recieve a roomGoodbye for them. The default state of a player after a roomHello is considered to be active.

As with a roomHello, it is courteous to reply to a roomJoin with a location response.

Everything else.

The rest of the packets you’ll receive are chat/commands destined for your room, and they’re structured like this:

room,<roomId>,{
    "username": "username",
    "userId": "<userId>",
    "content": "<message>"
}

The content attribute is the line of text entered by the user. The convention is that if the content begins with a / that the content should be treated as a command, else it should be dealt with as 'chat'.

Location, Location, Location

After you receive a roomHello, you should reply with a location response. In Game On terms, this is you sending back the room description for the client to render for the user. The protocol documents the location response like this..

player,<playerId>,{
    "type": "location",
    "name": "Room name",
    "fullName": "Room's descriptive full name",
    "description", "Lots of text about what the room looks like",
    "exits": {
        "shortDirection" : "currentDescription for Player",
        "N" :  "a dark entranceway"
    },
    "commands": {
        "/custom" : "Description of what command does"
    },
    "roomInventory": ["itemA","itemB"]
}

Here we see all the information a room can send back to greet a newly joining player. Most of this is self-explanatory, but here’s a brief overview of how the data connects to the user experience.

The exit information that a room might provide is descriptive only. Because rooms move around in the map, your room never quite knows who its neighbors are, and that is to be expected. You can provide alternate/fixed descriptions for some of the doors in your room, which might be useful if you had some kind of puzzle to solve. We’ve wanted to get wormholes working for awhile (where you define extra doors that go places), so if you feel like making this one work, we’ll take the help with enthusiasm.

Chat!

Your room is responsible for handling chat: specifically ensuring that chatter coming in from one player is broadcast to all other connected players. When you recieve a room message where the content is not prefixed with / you should reply with a chat message, which have a format like this:

player,*,{...}
{
  "type": "chat",
  "username": "username",
  "content": "<message>",
  "bookmark": "String representing last message seen"
}

The chat message is fairly self-explanatory, the username field carries who sent the chat message, content is what they said, and bookmark, as mentioned earlier, is a unique value for this message.

The target of this message is *, which allows everyone to see it, otherwise it wouldn’t exactly be chat. ;)

Replies to user / room.

Chat has a particular style when displayed in the UI, it’s marked out as who said it, and in a different colour to text like the room description etc. There will come a point when your room needs to respond in ways other than chat, eg. If you implement /examine shoes you wouldn’t expect the reply to come as username says the shoes look rather tall, but rather The shoes have a rather excessive heel.

To send a non-chat type response, we use a room event message, which comes in two varieties.

The first allows you to send a response just to a single user:

player,<playerId>,{
    "type": "event",
    "content": {
        "<playerId>": "specific to player"
        },
    "bookmark": "String representing last message seen"
}

Notice how the recipient in the header is set to <playerId>, this routes the message only to the player with user id playerId.

The second variety allows for content to be targetted to multiple places:

player,*,{
    "type": "event",
    "content": {
        "*": "general text for everyone",
        "<playerId>": "specific to player"
    },
    "bookmark": "String representing last message seen"
}

Notice how the recipient in this variety of event is set to *, and the content block allows for both content per user id, and content to be sent to everyone else.

This type of message is great if you want to implement the typical text adventure approach of sending You look at the shoes to the player, while sending Playername looks at the shoes to everyone else.

Moving on..

Lastly, Rooms should implement /go!

It is up to the room to agree that a player should leave when the player issues /go N or similar.

This allows for rooms to create basic puzzles where the doors can remain 'locked' because the room won’t allow the player to transition (except via /sos which the room has no part in), until a puzzle has been solved. It also allows a room to decide if a player should leave, even if the player does not issue a /go command first!

playerLocation,<playerId>,{
    "type": "exit",
    "content": "You exit through door xyz... ",
    "exitId": "N"
}

If a room sends this message, the Mediator treats it as a request to transition the player out of the room, in the direction indicated, and will send the content text to the player affected.

Notice although this message has a type of exit, its the target field here that’s the important difference, the target of playerLocation routes this Message in Game On to the code responsible for maintaining & transitioning players between locations.

The exitId here should be short name of an exit from the current room. Eg, N,S,E,W

The simple implementation of /go <direction> just parses <direction> and converts it into the appropriate shortname, before issuing the playerLocation message, but there are alternatives. One option is to invent an obstacle or puzzle that must be solved before sending the playerLocation message. A more complex option could use the Map REST API to retrieve the exits currently mapped around itself, and manage what’s allowed via /go based on that data! Just bear in mind that rooms do move around in the map…​