SerGIS Project

A system for "serious" GIS games

Table of Contents

Client Developer Documentation

Promises in Frontends and Backends

Any property of a frontend or backend that is a function must return a JavaScript Promise that is resolved with the value in question (or resolved with no data if the function does not return a value) after the function has completed.

In the case of an error, the function should reject the promise with a human-readable error message (starting with a capital letter and ending with a period).

Calling a function that returns a promise should look something like this:

getSomething().then(function (value) {
    // ...
}).catch(sergis.error);

If you want to do something special if the promise is rejected (as opposed to just reporting/alerting it through sergis.error), do something like this:

getSomething().then(function (value) {
    // ...
}, function (error) {
    // ...
}).catch(sergis.error);

Never forget the .catch(sergis.error) on the end, just in case one of the then functions throws an error!

Frontends

In SerGIS, a frontend is a JavaScript library for the SerGIS Web Client that handles the rendering of the map and the rendering of Map Action objects on the map. This is separate to easily allow different mapping APIs and libraries to be used.

Each frontend is a JavaScript object. It must be assigned to sergis.frontend.

This object must have the following properties:

Property Type Value
name string The name of the frontend (usually matches the frontend filename without .js on the end).
actions object The actions that the frontend can do to the map. It must have a function for each Map Action that could be present in an Map Action object (not including Gameplay Actions such as explain). The function name corresponds to the action’s name, and the function’s parameters correspond to data passed in the action’s data array.

This object must also have the following functions:

Function Name Arguments Return Value Description
init mapContainer (DOM element), map (Map) Promise<array> Initialize the map within the DOM element mapContainer, centering it based on the SerGIS Map object provided. If successful, the Promise should be resolved to an array representing toolbar buttons to show in the toolbar at the top. Each button is represented by an object with an id property (this must be unique to the frontend), a label property (which is a SerGIS Content object), and an optional tooltip property (a string).
reinit (optional) mapContainer (DOM element), map (Map) Promise Re-initialize the map within the DOM element mapContainer, centering it based on the SerGIS Map object provided. If not provided, then init is called if the map has to be re-initialized.
centerMap map (Map), mapCenterChanged (boolean) Promise Center the map based on the provided SerGIS Map object. If the latitude, longitude, or zoom have new values in the backend-provided data for the prompt, mapCenterChanged will be true. (Otherwise, you should keep the map centered where it is.)
mapContainerResized (optional) none Promise Resize the map to fit the size of its container. This is called after the size of the map container is changed for any reason, including window resizing.
toolbarButtonAction buttonID (string) Promise Execute the toolbar action for the toolbar button identified by buttonID. (Only ever called if init included at least one item in the array that its promise was resolved to.)

Backends

In SerGIS, a backend is a JavaScript library for the SerGIS Web Client that handles the interaction between the server and the client UI (or the interaction between a SerGIS JSON Game Data file and the client UI).

If a server is used, the server that is used through the backend must keep track of the actions that the user has completed so far (and which prompt index the user is on). This is separate from the main SerGIS code to allow the implementation of different backends corresponding to different server-side programs.

Each backend is a JavaScript object. It must be assigned to sergis.backend. This object must have 2 properties, account and game, which hold the functions for the backend.

Action Preprocessing

If you wish to support the deprecated goto or endGame actions in your backend (see Action Object), the backend must do a bit of preprocessing. When the client calls the game.pickChoice function on the backend, the backend must remove any goto and endGame actions from the list of Action objects (from whatever JSON Game Data the backend uses as a source) before returning it. The backend should then put the value of the goto action into the nextPromptIndex slot in the Choice object (or, if an endGame action was used, it should set nextPromptIndex to “end”).

Any other actions, including other Gameplay Actions (e.g. explain) or any Map Actions, can be passed to the client as-is, and the client will process them.