Minimap: An interactive dynamic decision making game for search and rescue missions

Abstract

Many aspects of humans’ dynamic decision-making (DDM) behaviors have been studied with computer-simulated games called microworlds. However, most microworlds only emphasize specific elements of DDM and are inflexible in generating a variety of environments and experimental designs. Moreover, despite the ubiquity of gridworld games for Artificial Intelligence (AI) research, only some tools exist to aid in the development of browser-based gridworld environments for studying the dynamics of human decision-making behavior. To address these issues, we introduce Minimap, a dynamic interactive game to examine DDM in search and rescue missions, which incorporates all the essential characteristics of DDM and offers a wide range of flexibility regarding experimental setups and the creation of experimental scenarios. Minimap specifically allows customization of dynamics, complexity, opaqueness, and dynamic complexity when designing a DDM task. Minimap also enables researchers to visualize and replay recorded human trajectories for the analysis of human behavior. To demonstrate the utility of Minimap, we present a behavioral experiment that examines the impact of different degrees of structural complexity coupled with the opaqueness of the environment on human decision-making performance under time constraints. We discuss the potential applications of Minimap in improving productivity and transparent replications of human behavior and human-AI teaming research. We made Minimap an open-source tool, freely available at https://github.com/DDM-Lab/MinimapInteractiveDDMGame.

Appendices

Appendix

A Minimap: Generic instructions

Fig. 9

Instructions on how to use the controls to play the game

B Customizaing experiments with minimap

This section presents how to set up an experiment with Minimap as an introductory tutorial and web service API methods in the current version of Minimap.

B.1 Preparation

Running the Minimap server requires MySQL database.

• Install MySQL for your operating system (Win/Mac/ Linux)

• Check that MySQL are installed. Open a terminal or a command prompt and run:

  

• Connect to the MySQL server, run

  

  user represents the user name of your MySQL account. Substitute appropriate values for your setup. MySQL will display a prompt to enter the corresponding password.

• From the mysql prompt, create a database:

  

• In a command shell, import the SQL script named script.sql provided in the project folder

  

B.2 Installation/Quick start

• In a command shell, go to the main folder that contains the requirements.txt file.

• Create a virtual Python Environment is recommended by running the following commands in your shell. (This may be different on your machine. If it does not work, look at how to install a virtual python env based on your system):

  

• Install the required python libraries by running this command in your shell:

  

• In the file mission/db.py, update the database configuration according to the database setup in the local machine, as in the following example:

  

• To start the server, run:

  

• While the server is running, navigate to: http://0.0.0.0:5700

• To stop the server, run Ctrl+C

B.3 Running an experiment with minimap

• After the server is started, launch the default search and rescue mission by connecting to:

  

  The port number can be configured in the server.py file.

• To check the replay interface, visit:

  

• Web service APIs for getting information about the playing score and the current game episode:

  

B.4 Directory structure of an experiment

The experiment folder called mission contains the following fundamental sub-folders and files:

The mission/static folder contains all the static files the game will serve. In particular, the mission/static/ data folder includes all the base or new map template designs, while the mission/static/js folder compriese of all the files defining the behavior of the game. The mission/templates folder contains all the html files that define the game’s interface.

The database configuration is declared in the mission/ db.py file while mission/main.py file controls the web service APIs available for use. Importantly, as described earlier, all essential DDM features are fully customizable in Minimap. One can configure the experiment settings by changing the appropriate values in the mission/config. json file.

B.5 User modifiable configuration parameters

We now describe how experimenters can customize the game setting through Minimap configuration to fit the scientific requirements of the scientific endeavor.

The experiment settings are specified in the file mission/config.json. This file contains the variables needed to define the functioning of the experiment as follows:

Condition Name

As it is likely that an experiment will be run under multiple conditions, the parameter “cond_name” is used to identify each experimental condition. One can change the default condition name, and make it short and descriptive.

Interface Modification

Minimap, by default, features the environment as illustrated in Fig. 1 provided that the environment design is customizable. To create different environments, one can customize the Minimap layouts, including the location and the number of objects on the map (e.g., victims, walls, obstacles, and doors). Technically, this can be achieved without requiring specialized technical knowledge: modifying the base map designed in the Excel file, placed in the folder (mission/static/map_design.xlsx), and then saving it as a CSV file. Afterward, it is needed to specify in the config.json file that the newly designed layout is used for the game (“load_new_map”: 1, 0 otherwise) together with the name of the new map in CSV configuration (“map_file”: “map_design.csv”). The width of each tile/cell in the gridworld is set by the variable “tile_width”. One can increase or decrease this value to adjust the size of the map. Detailed instructions on how to modify a task interface are presented in B.7.

Time Constraints

The variable “game_duration” controls the duration of playing time within an episode. The value is in seconds, so for a 5-minute mission, the duration is set to 300.

Complexity

Minimap provides two levels of structural complexity: simple and complex. For example, the configuration file above makes the game environment complex with (“complexity”: “complex”). Structural complexity is determined based on the number of obstacles and the arrangement of critical victims (see Fig. 2 and “Complexity” for more details). One can freely create new maps with different layouts and numbers of objects by following the steps described in the interface modification section.

Visibility

Minimap includes three levels of visibility to manipulate, namely the field of view (fov), map view (map), and full view (full). This degree of visibility is specified by “visibility” in the config.json file. With a field of view, the individual can only obse80rve part of the environment within their restricted vision area. In contrast, with a map view, they can see the overview structure of the map in addition to their vision area (Fig. 3) for more details). Conversely, the full view gives the player a complete picture of the environment, including where the victims are.

Time Victims Die

The moment victims die in the search and rescue task can be varied through the variable “victim_die”. For example, in the above configuration file, critical victims die or disappear from the building after two minutes (120 seconds) of the game.

Delayed Time

The delay in the individual’s actions, associated with the dynamic complexity, is integrated into Minimap by the variable “delayed_time”, measured in seconds. The affected activities include victim-saving and door-opening. In the example above, the delay period is set to one second, meaning that after the player executes an action of rescuing a victim, it takes one second for the effort to take effect. The action occurs immediately with a delayed time of zero.

Perturbation Time

The variable “perturbation_time” controls when a perturbation or a sudden change within an episode occurs measured in seconds. For example, during a 5-minute mission, if the perturbation takes place after 2 minutes of gameplay, then the value to 120.

Perturbation Map

The variable “perturbation_map” specifies the file associated with the new scenario layout once a perturbation occurs. The file is in CSV format as in the map design file.

Number of Playing Episodes

The number of times an individual can perform the task is a variable in Minimap. For example, “max_episode” in the config.json file above controls the number of playing episodes “max_episode”: 8 i.e., the default value is 8). This feature allows experimenters to run experiments multiple times to examine the human learning process.

B.6 Reproducing the experiments on complexity and opaqueness with Minimap

To reproduce each experimental condition described in “Proof of concept: Experiment on complexity and opaqueness with minimap”, one can configure the corresponding parameters in the config.json file under folder mission as follows.

Condition 1. Simple FoV:

Condition 2. Simple Map:

Condition 3. Complexity FoV:

Condition 4. Complexity Map:

Start the server and launch the new task scenario by connecting to:

B.7 An example of creating a task scenario

This section describes a step-by-step guide for creating a task scenario in Minimap. Suppose that in this new scenario, a player is instructed to navigate the $19 \times 19$ environment to save three types of victims: critical (red) victims, serious (yellow), and minor (green) victims. The player needs to play 10 episodes of a 3-minute game. A perturbation occurs after one minute of the game, which entails the sudden appearance of rubble and an increased number of serious and critical victims. The serious and critical victims vanish when two minutes elapse.

B.7.1 Step 1: Creating the environment layout

We create a map design file in the Excel configuration (e.g., “map_design_c.xlsx” as illustrated in Fig. 10a). Afterward, we save it in the CSV (“map_design_c.csv”) and place it in the folder mission/static/ (see Fig. 10b).

Fig. 10

Illustration of map design (in the Excel and CSV format) for the new scenario

The code number of each object in the environment, together with their associated action and reward, is described in Table 3. One can easily adjust the value of rewards and/or the number of button presses needed to obtain each object. The reward for obtaining each object and the number of keystrokes required for such action is defined in the column “Press” and “Reward”. For instance, change the values of the two columns “Press” and “Reward” in the third row of the table to adjust the number of key presses needed and the reward received by saving the green objects.

Table 3 Object codebook of Minimap

B.7.2 Step 2: Adding perturbations

We can intensify the task dynamic with sudden perturbation in the middle of the gameplay (within an episode). To do that, we design a new setting when the perturbation happens in the Excel file. When one minute elapses, the player will suddenly experience the appearance of rubble and an increase in critical and serious victims. We name the file, e.g., “map_perturbation_c.xlsx” as illustrated in Fig. 11a. We also save the design file in the CSV format and place it in the folder mission/static/ (see Fig. 11b).

Fig. 11

Illustration of perturbation design (in the Excel and CSV format) for the new scenario

B.7.3 Step 3: Configurating experiment parameters

For the task described above, we adjust the file config.json in the folder mission as the following:

Fig. 12

Display of the new task scenario in Minimap

Since we use the newly designed interface for the task, the value of “load_new_map” variable is set to 1 (true). We also increase the value of tile_width variable to 20 to expand the size of the grid environment. By default, the visibility (opaqueness) is set to full view (“full”). We can assign the value of the variable visibility to “fov” or “map” for displaying the task with the field of view or map structure, respectively (Fig. 12).

B.7.4 Step 4: Running the task

We start the server by typing:

Once the server is started, launch the new task scenario by connecting to:

Fig. 13

Illustration of the task environment when the disruptions take place

Fig. 14

Illustration of the replay function with the new task scenario

The interface of the new task with the full view and map view is illustrated in Fig. 13.

Fig. 13a illustrates the environment when the disruption happens (i.e., rubble appears, and the number of critical (red) and serious (yellow) victims grows). Figure 13b shows the setting after the time in “victim_die” variable elapses (i.e., the critical and serious victims disappear).

A-.7.5 Step 5: Repalying recorded data files

We can replay the recorded data files by entering

Then select the data file to display the playback illustrated in Fig. 14.