Level Up Documentation

This page serves as the primary developer-facing documentation for the Level Up project for the Strong Museum of Play in Rochester, New York.

It covers the REST API to interact with the metagame, example use cases, instructions on accessing the Django admin site, and guidelines for interacting with the RFID readers in the physical space.

There are some concepts in the metagame that will be useful as you start developing:

• Player - a top-level object that represents one visitor to the venue.
• Character - the visual representation of a player in the space. A Character consists of a top, middle, and bottom, as well as a display name.
• Verb - an abstract representation of an action that you can take in a game. Verbs are used to identify Achievements (see below) and are unique.
• Achievement - a specific instance of a Verb, which can be awarded by a game. For example, the Endless Runner game might award the "Track Star" achievement, which represents the verb "Run".
• Meta Achievement - a group of one or more Achievements, Icons, or Artifacts. Collecting all of the sub-items automatically awards the player the Meta Achievement. Meta Achievements are not associated with Verbs.
• Icon - a piece of virtual inventory that a player can collect. Icons are awarded by tapping an RFID band at special readers around the exhibit. Once an icon is found, it is in the players inventory forever.
• Artifact - another piece of virtual inventory that a player can collect. Artifacts are chosen by the player at vending machines around the exhibit and can be freely swapped out.

In the exhibit space, players are given a band that has already been associated with a player in the database (account creation is part of the responsibility of this server, but it is not the responsibility of exhibit developers). As they interact with games in the exhibit hall, they find inventory items, earn achievements, and collect artifacts that are then associated with their account. That's where you come in! Individual games are responsible making the API calls that assign new achievements to player objects. Each interactive communicates with two servers: this one, and an RFID server that is responsible for registering band taps and providing lighting cues to communicate the state of the interactive. The following example will help clarify.

The primary service of this application is to provide a REST API for interacting with the Level Up metagame. The API is accessible at `{this url}/api`. You can browse the API by navigating to that endpoint in a browser, or you can interact with it as normal, via REST requests (more on that later).

Before you start programming, collect the following:

1. The list of Achievements your interactive will award, along with their unique slugs.
2. The IP address of the RFID server you'll be connecting to.
3. A username and password to the metagame server (one per vendor, preferably).

The RFID server is responsible for registering band taps and displaying lighting cues to communicate the state of the interactive.

There are several preset lighting commands that you should use during the lifecycle of the interactive. The following table includes the names of each preset along with their UI/UX function and use type.

Each pattern is categorized either as idle or temporary. You can think of idle patterns as a default state, and temporary patterns as momentary overrides. A temporary pattern will override the current idle pattern, and return to that same idle pattern when the temporary pattern duration is over. The return to the idle pattern is done automatically, so you don't need to worry about triggering it manually. You will need to send commands to update the current idle pattern (e.g., to transition from the `OFF` pattern to the `ATTRACT` pattern.)

Also note that setting an idle pattern will never override a tempoarary pattern, so you can do things like setting `SUCCESS` and `OCCUPIED` at the same time. The temporary pattern (`SUCCESS`, here) will be displayed until the end of its duration, then the idle pattern will take over. These different categories are discussed in more detail below.

A note on using the `BUSY` pattern: This is intended to be a kind of waiting indicator for long-running requests. We recommend using it as follows:

• When a player taps a band, start a timer for 1 second.
• If the player lookup comes back before the timer expires, `BUSY` is not needed - just show `SUCCESS` or `FAILURE` as appropriate.
• If the timer expires before the lookup comes back, show the `BUSY` pattern.
• When the long-running request returns (or times out) show the appropriate temporary response and set the new idle pattern.

The idea is that most of the time, `BUSY` will not be shown, but in the cases that it is, its minimum duration is 1 second so that the lights don't look like they're glitching.

A final note: it is possible to set the lights to custom values (e.g., blink orange instead of purple). However, we strongly recommend that only the presets are used in the Level Up exhibit. If you must use custom lighting, please contact the Strong to discuss.