Skip to content

Show Config File definitions

Understanding the configurations

Below is an example of the YAML file that configures a show.

Show Configuration

# Shows

shows:

  - name: "LP_1"
    stage: "Stage1"
    appname: "LP_demo"
    version: "0.0.1"
    onboard_area: "OnboardArea_1"
    offboard_area: "OnboardArea_1"
    transform: [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]]
    group_size: 6
    max_groups: 7
    extra_args:
      - "-verbose"
    onboard_is_start: false
    max_onboard_groups: 1
    max_combined_groups: 1
    group_wait_seconds: 0
    earliest_device_assign_seconds: 90
    earliest_send_to_onboard: 60
    earliest_group_onboard_seconds: 120
    onboard_bounds: 
      front_left:
        x: -12.5
        y: 0.0
      rear_right:
        x: -11.0
        y: 5.5
    offboard_bounds: 
      front_left:
        x: -12.5
        y: -5.5
      rear_right:
        x: -11.0
        y: 0.0

name: This is a unique name for the show. If a location has only one show with a particular experience, then it can be the same as that experience's appname for clarity's sake. If a location has multiple shows running the same experience, then the operator should define unique names for each to allow them to be easily identified. This is the name that shows up in the GUI in the list of shows that the Operator selects when specifying what to be controlling with the UI. Spaces are not allowed in the name.

stage: Specifies which stage definition is used to host this show.

appname: The app name of the experience being presented at this show. The experience name is defined by the experience package that is received from the developer and loaded by the "gem admin db loadapp" command. You can list the experiences availabe to you with the "gem experience list" command.

version: The version of the app name being presented at the show. Many versions of an experience can be loaded on a system at the same time. A show needs to specify which version it is using. Just loading a new version of an app with the "gem admin db loadapp" command will not automatically switch any shows to using that new version. In a production environment this is an important consideration because it allows the operator to install new shows and create test shows to see if the new version works before switching over existing shows to use the new version. The "gem experience list" command lists all the experiences and versions available. The version string specified here in the show definition must be exactly the same as the one in the experience definition.

onboard_area: Specifies which operations area is used to onboard people for this show. One way to think about "operations" areas is about "pools of headsets/devices". It is not a matter of physical space but rather about headsets configured a particular way. When headsets have a set configuration (such as an HTC VB+ LBE map, for example) they need to be managed separately from those headsets that have a different configuration. If a site has multiple shows running the same experienece, but using different headset configurations because of different LBE maps, then each of those shows must use a different operations area for the onboard_area because they are using different pools of headsts that are not interchangeable.

offboard_area: Specifies which operations area is being used to offboard people for this show. In almost all circumstances the offboard_area should be the same operations area as the onboard area because they are using the same pool of headsets.

transform: The transform applied to the tracking space for this instance of the show. This allows for making adjustments to the precise location of the show within the trackable space. For GEM 1.0, only translations are supported, which are in the fourth row. For example, if I want to shift the center point of a show 3 meters forward, 5 meters to the right, I would set the transform to be:

transform: [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [3.0, 5.0, 0.0, 1.0]]

This value is usually determined as the real-world delta between the center of the LBE area and the center of the stage expected by the Experience definition.

group_size: The maximum number of people that GEM will onboard in a single group. It should be less than or equal to the maximum number of people supported by the experience.

max_groups: The maximum number of in-experience groups allowed on stage at the same time. This is not used in version 1.0 of GEM but is reserved for future version.

extra_args: These are extra command-line arguments that will be passed to the game server when starting up. The user can add/modify command-line arguments to the server in the experience definition (in which case they will impact all shows at a location) or here in the show definition so that they impact only one show.

onboard_is_start: Specifies whether the experience actually starts in the onboard area (or whether onboarding is happening in the first zone of the experience). This is usually false.
Note: There are very few reasons to set this to true. This was created for a small demo content and should never be used for any larger content or loop-around shows.

max_onboard_groups: The maximum number of gem groups that can be onboarding at the same time. This is going to be dependent on the onboarding space being used for the show and how it has been configured by the operator.

max_combined_groups: This parameter currently means the maximum number of groups that can be onboarding at the same time, including the one in the first zone if onboard_is_start is true. If onboard_is_start is false, this value should be identical to max_onboard_groups.

group_wait_seconds: When onboarding, this defines an "extra" time in seconds, beyond that which is necessary, that GEM will wait before onboarding group that is not at full capacity to see if another team arrives that can fill it up completely. Typically this value only makes sense in non-looping shows where there is no constraint on onboarding beyond a free zone 0. In looping shows, there is usually extra waiting time because of the looping aspect of the show and this value can be 0..

earliest_group_onboard_seconds: This value should be the time, in seconds, that is used by the onboard tutorial. It basically defines the minimum amount of time before zone 0 is available for the experience to start, that the onboard tutorial should start. If this value is less than the length of the onboard tutorial, then there will be a delay in the optimal start of the experience for the group and throughput will be impacted. If this value is longer than the length of the onboard tutorial then the onboard tutorial will start a bit early and the group will have to wait between the end of the tutorial and the start of the experience.

earliest_send_to_onboard: This value indicates how long before the start of the onboard tutorial the group should be directed to walk from the device assignment area to the onboard area. The value should be proportional to the walking distance/time between the two areas. If device assignment is happening in the same place onboarding, this value can be 0, but it is recommended that the "suitup time" of how long it will take the guests to put on their headsets be included in this value. THus if the stage is 30 seconds walking distance from the device assignment area to the onboard area, this value should be about 60 seconds.

earliest_device_assign_seconds: This value indicates how long before the group needs to start walking towards the onboard area the system should notify the group that they should go collect their headsets. This value should be set to the typical length of time it takes a group to notice their name on the Queue Monitor, proceed to the device assignment area and get their headsets assigned. About 90 seconds is a good starting point.

onboard_bounds & offboard_bounds: In the definition of the show, the operator can now define an onboard area and/or an offboard area. For backwards compatibility, if these areas are not defined, then GEM defaults them to be a 1.5 meter strip along the entrance to the first zone and the exit of the last zone.

The areas do not have to be continuous with the stage. See example above for details.

The coordinates are specified in meters and are the unsifted raw coordinates. Thus, if you move the show around by modifying the transform, you do not have to update the onboard_bounds or offboard_bounds as they will shift with the reset of the zones.

The implementation has been done in a backwards compatible way so that people do not have to update their show definitions in their yaml files.

The GUI has been updated to display the onboard and offboard area.

Tests that need to be performed:

  • Upgrade of existing definitions:
  • When this version is first run, it will update the database. The first test is to make sure that existing shows operate the same as before and that their onboard and offboard areas now displayed in the correct position in the UI.
  • Need to make sure that modification of existing shows still works (fields other than onboard and offboard bounds) to make sure that there are complaints about missing bounds definitions. The user should not be required to add onboard and offboard bounds.
  • Addition of onboard and/or offboard bounds to existing show definitions. It should be possible to define one and leave the other as default without the system complaining.
  • Definition of new shows:
  • With bounds definitions
  • Without bounds definitions
  • GUI
  • Do onboard and offboard bounds show up in the correct location
  • Does the stage display correctly fit the stage into the available space so that scrolling is not required
  • Do user dots show up in right place