Protocol

Game On Rooms support the concepts of 'items' via the websocket protocol. This means there is a difference between sending a Room Description that has the items embedded in the description text..

And a description that leaves them out and declares them to the room via the protocol..

To understand how to do this, we need to look at the Game On Websocket Protocol..

The particular message we are interested in is the 'location' message, which carries the Room Description and other information back to Game On. It is this "other information" that we may use to tell the game about items in the room.

The location message is documented 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"]
}

At the end is the "roomInventory" field which may be used to pass an Array of Strings that represent the items in the room. When the game renders the list in the web interface, it looks similar to this:

Room's descriptive full name
----------------------------
Lots of text about what the room looks like

You notice:
o itemA
o itemB

The itemA, and itemB have been called out by the the game’s web interface, because they were present in the roomInventory part of the location message from the Room.

Java Sample Room

Within the sample room, the location message is built from details in the RoomDescription object, by the RoomImplementation object, using the Message object’s utility method createLocationMessage.

Here we see the method createLocationMessage building up the response to send..

public static Message createLocationMessage(String userId, RoomDescription roomDescription) {

    JsonObjectBuilder payload = Json.createObjectBuilder();
    payload.add(TYPE, "location");
    payload.add("name", roomDescription.getName());
    payload.add("fullName", roomDescription.getFullName());
    payload.add("description", roomDescription.getDescription());

    // convert map of commands into JsonObject
    JsonObject commands = roomDescription.getCommands();
    if ( !commands.isEmpty()) {
        payload.add("commands", commands);
    }

    // Convert list of items into json array
    JsonArray inventory = roomDescription.getInventory();
    if ( !inventory.isEmpty()) {
        payload.add("roomInventory", inventory);
    }

    return new Message(Target.player, userId, payload.build().toString());
}

We see that the location message is built as JSON and the items are being read from the RoomDescription object passed as an argument.

The RoomDescription object offers the methods

   public void addItem(String itemName);
   public void removeItem(String itemName);
   public JsonArray getInventory();

Which would allow a Room implementation to add/remove items from the room, and thus from the description returned to the user.

Over in the RoomImplementation we see the simple processCommand method, that parses the input from the user and carries out the appropriate action. In this case, we’re interested in the /look command, which should trigger a location response.

Sure enough, there within the switch statement, we see a location message being built & returned to the user.

  case "/look":
  case "/examine":
      // See RoomCommandsTest#testHandle*Look*

      // Treat look and examine the same (though you could make them do different things)
      if ( remainder == null || remainder.contains("room") ) {
          // This is looking at or examining the entire room. Send the player location message,
          // which includes the room description and inventory
          endpoint.sendMessage(session, Message.createLocationMessage(userId, roomDescription));
      } else {
          endpoint.sendMessage(session,
                  Message.createSpecificEvent(userId, LOOK_UNKNOWN));
      }
      break;

If we wanted to add additional behavior, perhaps to support /examine itemName, this is where we could add it. Either as an extension to the switch block handling /examine and /look, or via an entirely new command. If the item were a button, we might like to add /push button as a command and send an appropriate response.

Let’s look at adding that button now.

roomDescription.addItem("button");

  } else {
      endpoint.sendMessage(session,
              Message.createSpecificEvent(userId, LOOK_UNKNOWN));
  }

  } else {
      if(remainder.contains("button"){
          endpoint.sendMessage(session,
              Message.createBroadcastEvent(username+" examines the button",
                              userId, "It's a big red button, you are very tempted to..."));
      }else{
          endpoint.sendMessage(session,
              Message.createSpecificEvent(userId, LOOK_UNKNOWN));
      }
  }

roomDescription.addCommand("/push","Pushes an item, like, a button?");

case "/push":
    // Handle the push command, response depends if user pushes button, or anything else.
    if ( remainder.contains("button") ) {
            endpoint.sendMessage(session,
                Message.createBroadcastEvent(username+" pushes the button. Nothing Happens. Surprising.",
                                              userId, "You push the big red button."));

    } else {
        endpoint.sendMessage(session, Message.createSpecificEvent(userId, "What do you want to push?));
    }
    break;