2.1 /newhub

This is called once during game set-up before any other functions are called.

The request body is the plain-text URL of the hub server.

You should POST to the hub server’s /register endpoint a JSON object with the following fields:

{ "url": whoami # the base URL of your domain server
, "name": "MP10" # the name of your domain
, "description": "An example domain based in Siebel 1404 and its surroundings."
, "items": domain_items # a list of all items you might give a player
}

The items field has the name, description, verb, and (if appropriate) depth fields. The id field will be assigned by the central hub and sent back as part of the reply.

The response from that URL will be a JSON object; it will have a single field error if something goes wrong; otherwise it will contain

{ "id": ... # a number identifying your domain
, "secret": ... # a string used to authenticate your domain
, "items": [...] # a list of item IDs in the same order as the request
}

It’s up to you to remember which item had which id; for example, domain_items[0]['id'] = response_data['items'][0].

The /newhub response should be a JSON object with a single field ok, the value of which is a string to show the user. If something goes wrong instead have a field error with a string to show the user and a non-success status code.

2.2 /arrive

This is called by the central hub server each time a user either (a) logs in or (b) returns to your domain after journeying elsewhere. It establishes the identity of the user, the inventory of the user, and items the user is expected to find your the domain.

The request body is a JSON object with the following fields:

{ "secret": ...    # the same string as from /newhub
, "user": ...      # a number identifying the user
, "owned": [...]   # items from this domain in the user's inventory
, "carried": [...] # items from other domains in the user's inventory
, "dropped": [...] # items the user left in this domain
, "prize": [...]   # items other domains want the user to find in this domain
}

Each dropped item has a location field indicating where it was dropped.

Each prize item has a a depth field indicating how many out-of-domain barriers the user should have to pass to find the item.

The response should have a 200 status code; its content is ignored.

2.3 /dropped

This is called by the central hub server each time a user drops an item in your domain.

The request body is a JSON object with the following fields:

{ "secret": ... # the same string as from /newhub
, "user": ...   # a number identifying the user
, "item": ...   # the item being dropped, including id, name, description, and verb
}

The response should be a JSON value indicating your own internal way of tracking where the user was when they dropped the item. This could be a string like "classroom", a numeric identifier like 340, a more complicated object like {"latlon": [40.11, -88.24], "building": "Siebel", "room": 1404}; its implementation is up to you. This same value will be provided in the dropped field of subsequent /arrive calls.

2.4 /command

This is called by the web user interface each time the user types something.

The request body is a JSON object with the following fields:

{ "user": ...      # a number identifying the user
, "command": [...] # a list of strings, the words that the user typed
}

The response should be text to show the user in response to this command. For simplicity of testing, we provide a set of strings to use as responses in various situations. You are welcome to add additional responses of your own if you would like, but not to edit the ones we provide.

As a special case, if your response begins "$journey " then the web UI will automatically run your response (minus the leading $) as if the user had typed it.

2.5 Item format

Items are represented in interactions with the hub as JSON objects or as integer identifiers. The JSON object will have a subset of the following fields:

{ "name": ...     # a single-word label for the item
, "description": ... # response to "look item"
, "verb": {...}   # a map of {verb: response to "verb item"}
, "id": ...       # integer id used by hub for this item
, "location": ... # a value you returned from /dropped
, "depth": ...    # an integer indicating how hard this should be to find
}

A word means lower-case ASCII letters, digits, and hyphens, but not just digits.

If the item was

{ "name": "widget"
, "verb":
    { "open":"It seems to be stuck."
    , "close":"It's already closed"
    }
}

then the command open widget would return the reply It seems to be stuck.

An item only has depth if it is created and owned by one domain but hosted and found by the user in another domain. When present, depth is a non-negative integer. For this MP, simply place items of a given depth in the specified locations. Additional meaning for depth will be added in the project.

2.6 The MP10 domain

There are three locations in the MP10 domain.

4.1 /transfer

This endpoint is used to move items in the hub’s item location tracking.

The request body should contain the following fields:

{ "domain": ... # your domain's ID as given during /newhub
, "secret": ... # your domain's secret as given during /newhub
, "user": ...   # the user ID as given in /arrive
, "item": ...   # a numerical item ID
, "to": ...     # where you want the item to go
}

If to is "inventory", the item will be picked up and carried with the user. Any other to value is treated as identifying a particular part of your domain where the item is being stored.

The response will be status 200 {"ok": "item transferred"} on success or a status between 400 and 499 with body {"error": "..."} if the transfer cannot be accomplished.

4.2 /query

This endpoint is used to discover what items the hub believes are in a given location.

The request body should contain exactly 4 of the following fields:

{ "domain": ... # your domain's ID as given during /newhub
, "secret": ... # your domain's secret as given during /newhub
, "user": ...   # the user ID as given in /arrive
, "location": ... # where you want to look for items
, "depth": ...  # what depth hosted items you want to be informed of
}

The request must include either location or depth but not both.

If given location "inventory", lists the items the user is carrying.

If given any other location, lists the items that were previously placed there using /transfer.

If given a depth, lists items owned by other domains but hosted in your domain that have that depth.

The response is a list of integer item identifiers. All of the identifiers will be ones that were the id field of an object provided in an earlier /arrive request.

5.1 Command standardization

The web front-end will edit what the user types as follows:

1. It will make the text lower-case, remove any non-ASCII characters, and convert to a single space between words.

   For example, Open the door becomes open the door.

2. If the first word is a prefix of a single known verb, it will expand it to be that verb.

   For example t key becomes take key because take is the only in-game verb that starts with t.

3. All articles³³ Articles: a, an, the and prepositions⁴⁴ Prepositions: about, above, across, after, against, among, around, at, before, behind, below, beside, between, by, during, for, from, in, inside, into, near, of, off, on, out, over, through, to, toward, under, with, aboard, along, amid, as, beneath, beyond, but, concerning, considering, despite, except, following, like, minus, next, onto, opposite, outside, past, per, plus, regarding, round, save, since, than, till, underneath, unlike, until, upon, versus, via, within, without are removed.

   For example, use the key in the lock of the door and use the key to lock the door both become use key lock door.

4. A list of alternative phrasings will be replaced with canonical form.

   For example, west becomes go west and take inventory becomes inventory.

5. If the verb is journey, drop, inventory, score, or region, the message is directed to the hub server.

   Otherwise, the message is directed to the current domain server.

The final value sent to /command will be a list of words. for example, if the user types Open the door, /command will be sent ["open", "door"].

5.2 General-purpose commands

Many commands will be specific to the locations you are creating, but some are more-or-less universal:

look

Displays the description of the user’s current location. Also displays any items that are visible in this location.

look item

Displays the description of that item if it is in the user’s inventory. You may also display that description if the item is in the same location as the user.

For this and other item commands, you must support identifying items by name; we recommend, but do not require, also supporting identifying items by ID.

take item

If the item is in the same location as the user, moves it into the user’s inventory.

drop item

If the item is in the user’s inventory, moves into the same location as the user. This command is handled by the hub, aided by the domain’s /dropped endpoint.

go direction

Moves the user in that direction within the domain, if possible.

If the entered location is one the user has not been to before, displays the description of the new location. If the entered location is one the user has been to before, may either displays the description of the new location or just its name, at your preference. Either way, also displays any items that are visible in this location.

verb item

If the user has that item in their inventory and verb is in the item’s verb field, displays the value of that verb of that item.

inventory

Handled by the hub; shows what the user is carrying.

journey direction

Handled by the hub; changes what domain the user is in.

6.1 Shared client

Your domain will send many requests to the same server (the central hub); if handled naively that will result in most of your code’s runtime being spent creating TCP connections. To instead re-use the same connection for many requests, we use aiohttp’s on_startup and on_shutdown to provide a single ClientSession you can reuse for each request.

This means that your requests will look like this:

@routes.post('/example')
async def example(req: Request) -> Response:
    ...
    async with req.app.client.post(url, json={'cs':340,'ex':'ample'}) as response:
          data = await response.json()
          ...
    ...
    return web.json_response(status=500, data={"example":"this code is not done"})

Do not make your own ClientSession; only use the one in app.client.

6.2 CORS

Cross-Origin Resource Sharing, or CORS as it is usually abbreviated, is a set of protocols and rules to guard against certain types of malicious behavior online. Because this game will have a browser visit a page hosted by one server and from that browser send requests to another page, we will run into the limitations of CORS.

Rather than explain the details of this concept, we will simply have the domain servers proclaim that they are willing to be contacted even in ways that CORS protections would usually prevent. We do this with what aiohttp calls a middleware, written and provided by us for you. Its presence should have no impact on how you code.

6.3 Strings to use

For simplicity of testing, we provide a set of strings to use as responses in various situations. You must use these strings as-is in those situations to get full credit on this MP.

These strings are a minimum set. You are welcome to make you domain more forgiving (for example, you could accept computer as a synonym for monitor), more expressive (for example, you could add a use bench action in the foyer), or more expansive (for example, you could add other locations, items, and the like).