(Created page with "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...")
 
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
On this page you will learn:
On this page you will learn:


* About the overall architecture of the entire simulation platform
*About the overall architecture of the entire simulation platform
* About the code setup:
*About the code setup:
** of the Unity Client
**of the Unity Client
** of the Server API
**of the Server API
** of the Watchdog and the Simulations
**of the Watchdog and the Simulations
 
For access to the actual source code, see the [[Community Contribution|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).


== Overall architecture ==
<br />
<br />
[[File:MSP Challenge architecture.png|alt=MSP Challenge Simulation Platform architecture|center|thumb|1000x1000px|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 [[Research publications|'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.


== Unity Client ==
==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. [[Server API calls by client|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:
 
#GameSession: the actual session to which MSP Challenge clients can connect, e.g. a North Sea edition instance.
#GameSave: a save of an actual session that can be reloaded or shared to others who can then import it into their own ServerManager.
#GameConfig: the configuration files with which MSP Challenge sessions can be created. Full [[Configuration data schema|documentation on the configuration data schema]] is available.
#GeoServer: instances of GeoServer containing appropriate vector or raster data layers that can be downloaded when creating a new session.
#Watchdog: instances of the Watchdog application (see also below) that control the simulations for each session.
#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:
 
<code>http://[address]/[sessionID]/api/[class]/[method]</code>
 
<code>For example: <nowiki>http://localhost/1/api/plan/ExportPlansToJson</nowiki></code>
 
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:
[[File:MSP Challenge Security Token Flow by Client.png|center|frameless|837x837px|MSP Challenge Security Token Flow by 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.
<br />
<br />
== Server API ==

Latest revision as of 11:50, 15 April 2024

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
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:

MSP Challenge Security Token Flow by 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.

This page was last edited on 15 April 2024, at 11:50. Content is available under GPLv3 unless otherwise noted.