Spy Game With a GPS Tracker

This tutorial is part of the Internet of Tricks Erasmus+ Project. By the end of the tutorial, you will create a Spy Game in Python, where users can figure out which persona is guilty from a list of suspects. As a demo, we started with the Meatball Thief, a game where you must find out who stole the meatballs from famous imaginary restaurants in Stockholm. The scripts are based on the article written by Leo Tisljaric on Medium: Simple GPS data visualization using Python and Open Street Maps.

You will need a computer with:

• Access to Internet
• Python installed
• An IDE to edit and run some Python scripts (PyCharm Community Edition, Visual Studio Code, or Anaconda are just a few examples).

The Meatballs Thief

First thing first, play the game so you will understand how it works. Remember, by the end of this workshop, you will create your own game.

You work for a secret service and are tracking someone stealing meatballs from restaurants in Stockholm. You have five suspects. Only one is guilty. Read the mission-overview.pdf file first to understand your mission.

Read the suspects.pdf file — or see the above images — to familiarize yourself with the case and the list of suspects. Please pay attention to tracking information (e.g., where they live, work, etc.) as it is important to solve the case.

You will use a Python script built and tested by top-rated coders from your spying agency. Follow the steps below to get things in motion:

1. Download a Python IDE if you don't already have one. We recommend PyCharm Community Edition (scroll to the bottom of the page to choose the free version).
2. Download the scripts. Go to this GitHub link, click the green button (< > Code), then choose Download ZIP. Save them locally to one of your folders (e.g., Documents).
3. Unzip the scripts and look around. All the files are under the spy-game-stockholm folder. You will find there:
4. Lists with GPS positions, titled data-00N.csv (where N is a number from 1 to 5). Unfortunately, some interns handled these files, and they messed things up. The file numbers are not related in any way to the suspects. So, for example, data-001.csv can be the tracking data for any of the suspects.
5. Lists with restaurants and homes of the suspects: data-locations.csv
6. The area where all these happened (the actual map): data-map.png
7. A script where all the magic is done: gps_class.py
8. The main script. This will be the one file you will need to run a couple of times to solve the mystery: main.py.
9. Open the Python IDE. Choose File > New Project from the menu and browse to the unzipped files. This will be the root folder of your project.
10. Install required libraries. To make things easier, your colleagues used some libraries (already written lines of codes and functions). You need to install them before running the scripts. Browse your project and open the file gps_class.py. On top of this file, you will see a couple of lines starting with the words import or from. If you hover the mouse over these lines, you will see suggestions from the IDE. You can install each library using these suggestions. Close the file.
11. Run the script. Open the main script, main.py. Look for a row that starts with data_path = N (where N is a number). You must change that number to 1 so the line will become data_path=1 and run the script. If everything is OK, the file will generate an image titled result-map-001.png, where you will find all the locations (houses and restaurants) and the tracking information from the first file (data-001.csv). Repeat this step for all your files (from 1 to 5). At the end, you should have 5 images as a result.

Finally, read the images generated by the script and use the mission-control.pdf file to add your information for each suspect. All this info should be enough to solve the case.

You will need to create a story before being able to build your own game. Please choose a location (town), a list of restaurants (4-5 will work just fine), and a couple of suspects and their connections. You can use generative AI tools like Google Bart or ChatGPT to "invent" the information for you. You will see the details below.

In your Python IDE, you can duplicate the folder spy-game-stockholm and rename it to match your story. For example, if you choose Tokyo, your new folder should be spy-game-tokyo. Also, make sure you also copied all the files.

You can choose any town you want, whether famous or not. Any option is fine if you think about a favorite meal served in that area. This is what the thieves will steal. Next, you will need names for your restaurants. Try to make this as real as possible. For example, if you choose Tokyo as your location and sushi as your meal, a restaurant called Bella Italia will not look good with your story.

If you choose to let a generative AI tool do your work, you can write a prompt similar to this one:

Please invent a list of 10 fictitious restaurants in [your_city] serving [famous_meal]. 
The restaurants should not be real.

You need to replace [your_city] and [famous_meal] with what you chose for your story. Although we suggest having no more than 4 or 5 restaurants, it is a good idea to think about more names, as you can figure out later which ones are the best. This is a good time to look at the map and choose some coordinates for your chosen restaurants. Here are some suggestions:

• Write the coordinates and the restaurants in a spreadsheet or any digital format file.
• Use Google Maps or any other online map tool to get the coordinates for each restaurant.

You can start changing the files from your folder with all this information. For this step, you can edit two files. Save your files as often as possible.

story.md

Having the extension .md, this is a Markdown type of file, a lightweight markup language that you can use to add formatting elements to plaintext text documents. If you are not familiar with this format, look at this introduction.

This is where you add information for those who will play the game. You must change the title, the Introduction chapter to match your story, and the Restaurants chapter with your locations. You can leave the rest of the information unchanged for now.

data-locations.csv

With the extension .csv, this is a Comma Separated Values file. This document stores tabular data (numbers and text) in plain text, where each file line typically represents one data record. You can read more about this kind of file here. The script will use this to point out where the restaurants are. So, you must provide values for each restaurant, one per row. You must leave the first row intact. An example file should look like this:

Location ID,Type,Latitude,Longitude
A,Restaurant,59.333926053729490,18.058587957402477
B,Restaurant,59.34017310668763,18.077184794178134
C,Restaurant,59.335478465732340,18.081823399900312
D,Restaurant,59.325708359795385,18.067297407296245

The Location ID column should only contain one letter. The Type column can be Restaurant or Residence (they will have different colors on the map based on this information). Latitude and Longitude should be as accurate as possible (as many decimals). You can leave the rest of the file intact for now.

At this point, you need to create stories for your suspects. We recommend having around 4-5 suspects. Each suspect should have the following information:

• First and last name
• A short description: short bio and what is their motive
• Occupation
• Residence
• Workplace

If you choose to let a generative AI tool do your work, you can write a prompt similar to this one:

You work for a secret service, tracking a person stealing [famous_meal] from restaurants 
in [your_city]. You have 5 suspects. Create a short story for each of them, including 
their name, occupation, and where they work and live. Only one is guilty. 
Explain who and why.

The information should be added to the same files as above, but this time to other sections. Save your files as often as possible.

story.md

Change the Homes and The Suspects chapters.

data-locations.csv

Add the rows for the residences of your suspects. Make sure to use Residence as a value in the Type column. Again, be as accurate as possible with your Latitude and Longitude coordinates.

At this step, you must create [N] files, each titled data-00[N].csv, where [N] is the number of suspects. For example, you will need five files if you have five suspects.

Each file should contain 50-60 GPS positions (Latitude and Longitude). Together, the coordinates should easily predict a route for the suspect. The route must be linked to at least a residence and a restaurant. You can use the same tool used before to get the coordinates of the restaurants. Save the files.

In a real-life scenario, a device would have generated these files. Read this tutorial for more details.

You must download an image as your map background for the whole game. The map can be downloaded from Open Street Map:

• Navigate to the part of the map you need.
• Zoom in to include all your locations and the coordinates of the suspects.
• Click on the Export button (top part of the screen)
• Click on the Manually Select different area (under the coordinates, on the left side and select the desired area (move the corners on the map, if needed).
• Click on the Share button (on the right).
• Check the Set Custom Dimensions checkbox under the Image section and move the second set of corners to overlap the first ones.
• Write down the coordinates of the upper left and lower right corners in this case (35.7534, 139.6843) and (35.6337, 139.8330). You will need these to modify your scripts.
• Save the image by clicking on the blue Download button at the bottom of the right side. Save your image with the name data-map.png in your folder. You can overwrite the old file.

This is a good moment to update the main.py script. In line 7, you need to change the old coordinates with the new ones that you just wrote.

Test your game. Play it from the beginning. See if all the resulting images remain are generated correctly. Make changes if you see bugs in your data. Share your game with others! Also, you can decide to upload your version to GitHub.

Discuss with the other teams how a tracking device can be beneficial and risky. Give some good and bad examples for both scenarios.

This tutorial was developed as part of the Internet of Tricks project, co-financed by the Erasmus+ program of the European Union. Project n°: 2021-1-SE02-KA220-YOU-000028971. The content of this publication does not reflect the official opinion of the European Union. Responsibility for the information and views expressed therein lies entirely with the authors. For more details, contact Small Academy.