Source code documentation

On this page you will learn:

• About the overall architecture of the entire simulation platform
• About the code setup:
  • of the Unity Client
  • of the Server API
  • of the Watchdog and the Simulations

For access to the actual source code, see the source code contributions page.

Overall architecture

The following diagram depicts the overall technical architecture of the MSP Challenge Simulation Platform.

The server consists of three main parts: the MSP Challenge server side (left), hosting server side (middle) and client side (right).

MSP Challenge Simulation Platform architecture

The MSP Challenge server side consists of three main components: an authentication server (1), a map server (2), and an MSP wiki (3). These server components take care of the underlying functions such as user and session authentication and the connection to a data server. This is needed to host, moderate and play an MSP Challenge session. At present Breda University of Applied Sciences hosts and maintains these components.

The hosting server side allows institutions to host MSP Challenge sessions on a central or local server. This entire part (4-10) is packaged in the full platform installer, available from the Download page.

The client (0) was built in a Unity game engine and links via a RESTFul API to the game server (5). The MSP Challenge client is the end-user’s main conduit to the entire platform. Changes to the world by the players are sent to the game server which then replicates to the other clients connected to the same server. The client takes care of rendering visual information and supports all user interactions. This includes viewing the sea basin world in its current and future state. Players can sketch, implement or archive plans. The results are calculated by the simulators but displayed in the client through performance graphs, such as increases or decreases in biomass, shipping route efficiencies, or energy production.

You can read much more about this architecture in the paper 'A Digital Game-based Simulation Platform for Integrated Maritime Spatial Planning: Design Challenges and Technical Innovations', published in 2020 by the Journal of Ocean Technology, and available from the Research Publications page.

More about the Unity client's setup and code

The MSP Challenge Client (0 in the diagram above) currently uses Unity version 2020 LTS.

Server communications are done using the static ServerCommunication.cs class. In the very first session login screen the client communicates with the Server Manager API (see below). All server communication after that is with the server API directly, targeting a specific session that has already been set up on the server.

Practically all client-server communications goes through the Server.cs script. Here's an overview of all Server API endpoints called by the client.

More about the server's setup and code

ServerManager

The ServerManager is a separate PHP and jQuery web application running on the server's web address /ServerManager/. It has a back-end API with which the front-end HTML/CSS/jQuery end-user interface as well as the server API communicates.

The ServerManager API's structure follows the BREAD (Browse, Read, Edit, Add, Delete) actions that should be performed on the following objects:

1. GameSession: the actual session to which MSP Challenge clients can connect, e.g. a North Sea edition instance.
2. GameSave: a save of an actual session that can be reloaded or shared to others who can then import it into their own ServerManager.
3. GameConfig: the configuration files with which MSP Challenge sessions can be created. Full documentation on the configuration data schema is available.
4. GeoServer: instances of GeoServer containing appropriate vector or raster data layers that can be downloaded when creating a new session.
5. Watchdog: instances of the Watchdog application (see also below) that control the simulations for each session.
6. ServerManager: settings of the ServerManager application itself (e.g. its name, address, ...).

Server API

Underlying the ServerManager is a separate Server API. So this is a different PHP web application, and it runs on the server's root address. It listens to calls set up in the following manner:

http://[address]/[sessionID]/api/[class]/[method]

For example: http://localhost/1/api/plan/ExportPlansToJson

The sessionID refers to the actual MSP Challenge server session to which clients connect. Each session is set up in the aforementioned ServerManager.

A security system guards whether specific server API calls are actually allowed. This system is based on those calling an API endpoint providing an MSPAPIToken in their header. In turn this token must of course first be requested from the server. The diagram below shows how this works out for the MSP Challenge Client:

Watchdog and Simulations

The Watchdog is a C# application that handles communications between the Server API on one end and the different simulations required for a specific MSP Challenge session on the other hand. So for example, it handles the energy, shipping and ecosystem simulations required for an instance of the North Sea edition. The Watchdog is again an API on a web server, waiting for requests to e.g. start a simulation executable, or push it to do another month of simulation. It can thus be set up on a different machine than the one running MSP Challenge Server.