Show
Sidebar

SerGIS JSON Format Documentation

SerGIS has a special JSON format that is used to store its data. This JSON content is not usually directly available on the client-side, but rather it is used on the server-side so the server can push the data to the client as needed (or directly used by the backend if no server-side system is used).

SerGIS JSON Object Reference

These objects are referenced below in the JSON spec.

Action Object

A SerGIS JSON Action Object is an object representing either a “Map Action” (an action to do on the map) or a “Gameplay Action” (an action that affects the gameplay).

Gameplay Actions: These actions do not affect the map, but rather affect the game sequence. The names of these actions are:

* The endGame and goto actions are deprecated, and should not be used. Instead, authors should use the nextPrompt property in the actionList (see near bottom of this page). These deprecated actions are not implemented by the SerGIS client, but rather by the SerGIS backend (see Action Preprocessing for more).

Map Actions:

The names of map actions vary by frontend. Therefore, in order to support multiple frontends, you must provide a separate Action object for each frontend.

For example, the following could be a list of actions. Note how Gameplay Actions are only specified once, but Map Actions are each specified multiple times, once for each supported frontend.

[
    {
        "name": "explain",
        "data": [
            {"type": "text", "value": "Choice Explanation Here"}
        ]
    },
    {
        "frontend": "arcgis",
        "name": "buffer",
        "data": [120]
    },
    {
        "frontend": "googlemaps",
        "name": "buffer",
        "data": [120]
    }
]

Collectible Object

A SerGIS JSON Collectible Object represents a visual way to show to the user certain collectibles. These are shown in a special status bar in the interface. Each collectible uses a state variable behind the scenes to store and manipulate how many of the collectible there are. (For more on creating and modifying state variables, see State Variables.)

There are 2 ways of showing collectibles:

1. Numeric representation: This is simply a representation that shows the user how many of a collectible they have. Example: “Cows: 15”
2. Picture representation: This represents the value of the variable by showing an amount of pictures relative to how much of the collectible the user has. Example:
3. Bar representation: This represents the value in a “progress bar” format, or a bar that is filled relatively to how much of the collectible the user has. Example:

Condition Object

A SerGIS JSON Condition Object is an object representing a condition that can be resolved to true or false. It is used in the conditional version of nextPrompt (see near the bottom of this page).

The following conditions are supported:

Content Object

A SerGIS JSON Content Object is an object representing some sort of content that is part of a prompt or choice.

It must have a type property that identifies what type of content it is. The value of the type property determines which other properties are present.

The main value for the type is stored in value (which is required). CSS attributes can be specified by passing them in a string stored in style (this should match the formatting of the HTML style attribute). Some types have other possible properties too, all of which are optional (their default values are shown).

• Text Type: {"type": "text", "value": "plain text here", "centered": false}
• HTML Type: {"type": "html", "value": "<p>HTML content here</p>"}
• Image Type: {"type": "image", "value": "URL of image", "centered": true}
• YouTube Type: {"type": "youtube", "value": "youtube-video-id-here", "width": 400, "height": 300, "playerVars": {"autohide": 1}, "centered": true}

Map Object

A SerGIS JSON Map Object is an object representing a map state, including location (i.e. latitude/longitude) and zoom.

The map frontend is reinitialized before the prompt is shown if any of these are true:

• reinitialize is set to “before” or “both”
• reinitialize on the previous prompt was set to “after” or “both”
• The user jumped around (see SerGIS JSON Game Data)
• alwaysReinitializeMap is set to true (see SerGIS JSON Game Data)

Prompt Object

A SerGIS JSON Prompt Object is an object representing either a question for the user or information to show the user.

Example value for buttons:

"buttons": {
    "arcgis": {
        "measureButton": {
            "hidden": false,
            "disabled": true
        }
    },
    "googlemaps": {
        "measureButton": {
            "hidden": false,
            "disabled": true
        }
    }
}

SerGIS JSON Game Data

SerGIS JSON Game Data is a JSON file with a specific structure. The JSON data consists of an object with the following properties:

• The layout object has the following properties:

  Property	Type	Value
  defaultSidebarWidthRatio	number	A number between 0 and 1 indicating the default % of the horizontal screen real estate that should be taken up by the prompt sidebar. Default: 0.3
  disableSidebarResizing	boolean	Whether horizontal resizing of the prompt sidebar should be disabled. Default: false
  disableTranslucentSidebar	boolean	Whether the translucent prompt sidebar, with the map behind it, should be opaque instead, with the map only extending to its border and not behind it. Default: false
  defaultPopupMaxWidthRatio	number	A number between 0 and 1 indicating the default % of the map’s width that is allowed to be taken up by the popup. Default: 0.5
  showPromptNumber	boolean	Whether to show “Prompt __ of __” at the bottom of the prompt sidebar. (If any kind of jumping around is enabled, then this is always shown regardless of this setting.) Default: false
  hidePromptTitle	boolean	Whether to hide the prompt title at the top of the prompt sidebar. Default: false
  hideScoringBreakdown	boolean	Whether to hide the per-prompt scoring breakdown at the end of the game. Default: false

• Each object in the promptList array has the following properties:

  Property	Type	Value
  prompt	Prompt	The SerGIS Prompt object representing the prompt.
  actionList (optional)	array	An array of objects representing different actions. Each item in this array corresponds to a choice in the prompt.choices array. If prompt.choices is empty or not provided, then this can be empty or not provided. (This is separate from prompt so a server can send prompt on to the client without revealing the consequences of each choice.)

  • Each object in the actionList array has the following properties:

    Property	Type	Value
    actions (optional)	array<Action>	An array of SerGIS Action objects representing the actions to be taken if this choice is selected. (Actions are evaluated in the order that they appear in this array.) After these actions are taken, or if no actions are provided (i.e. actions is an empty array), the game will advance to the next prompt automatically (unless otherwise instructed).
    pointValue (optional)	number	The amount of points that the user should have added to his score for choosing this choice. If not provided, defaults to 0.
    nextPrompt (optional)	number|object	Go to a specific prompt after the user chooses this choice. If not provided, defaults to the next prompt (promptIndex + 1). See nextPrompt format below.
    setVariables (optional)	object<string, number>	Any numeric state variables to set. Each string key is the name of a variable, and the corresponding numeric value is the new value of the variable. For more on variables, see below.
    adjustVariables (optional)	object<string, number>	Any numeric state variables to adjust (i.e. increment or decrement). Each string key is the name of a variable, and the corresponding numeric value is the amount to add to the variable (can be negative to decrement a variable). For more on state variables, see below.

    nextPrompt format:

    • Simple “go to”: If it’s a number, it represents the next prompt index to go to.
    • Conditional “go to”: If it’s an object, each key is either a prompt index or the string “end”, and each corresponding value is a Condition object representing a condition that must be true to go to that prompt index (or end the game if “end” is used instead of a prompt index).
    • End Game: nextPrompt can be equal to the string “end” to instantly end the game.

    NOTE: Even if none of these properties are needed, actionList should still contain an empty object ({}) filling the position.

State Variables

SerGIS includes a simple way of giving a user a score via the pointValues that can be set for each action (which are then added up at the end to give the user his or her final score), but sometimes something more powerful is needed. State variables fill this place. They are numeric variables that persist with the user’s session as the user plays the game.

When a user makes a choice, state variables can be set, incremented, or decremented as a result of that choice (see setVariables and adjustVariables in the table above this). Then, the values of these variables can be used later in the conditional version of nextPrompt (which allow the next prompt to be chosen conditionally; see the section above this one).

Also, if the game creator chooses, certain variables can be shown to the user (for example, to show the state of certain collectibles that they might have). When a state variable is shown in some sort of representation to the user, it is called a Collectible. For more, see Collectible object above.

Example

An example can be seen in the sergis-client repository, in the testdata.json file (or see an older, commented version).