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.

Quick Links


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 Field

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.

Example Interactive

  1. A Player walks up to the Jumping On a Trampoline interactive. They tap their band on the glowing RFID reader, which reports the band ID as a string to the application.
  2. The interactive makes a GET request to the server with the band ID and receives a Player object in return. It sends a message to the RFID server to flash the lights in the SUCCESS pattern while the attract mode disappears and the interactive starts.
  3. No one else should be able to tap a band while the Player is in the middle of the game, so the interactive sends a lighting message to the RFID server to tell it to display the BUSY cue.
  4. The Player does well at the game - well enough to earn an achievement! The interactive has been assigned the achievement with the id `jump` (provided by the team at the Strong), so it makes a POST request to the server with the Player's ID and the Achievement ID (called a `slug`).
  5. The Player does not have the achievement already, so the server associates the Achievement with the Player. It sends back the updated player object as well as some metadata (see API section below).
  6. The interactive shows the Player the achievement and the game ends.
  7. Back in the attract mode, the game is available again, so the interactive sends the ATTRACT lighting cue to the RFID server in preparation for the next game.

Getting started

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).

RFID Server

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

General Use

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.

Preset Name Function Type
OFF No lights - displayed when the interactive is off. Idle
ATTRACT Displayed during attract mode when no users are at the interactive (but it is available to play). Idle
BUSY Displayed while RFID tap is processing. Idle (see above for recommended behavior)
SUCCESS Displayed when RFID lookup found a player. Temporary
FAILURE Displayed when RFID lookup did not find a player. Temporary
ERROR Displayed when an unknown error happened on RFID lookup. Temporary
OCCUPIED Displayed when a user is currently at an interactive, and it is not accepting new taps. Idle