GeoGami UI

Cross-platform mobile and web client for the GeoGami location-based game platform.

GeoGami is a location-based game built by the Spatial Intelligence Lab (SIL) at the Institute for Geoinformatics, University of Münster. The app lets users play and create map-based games in the real world or in a virtual environment, with the goal of training and studying spatial cognition.

This repository contains the front-end client — an Angular + Ionic application that runs as a web app, an iOS app, and an Android app from a single codebase.

Looking for the other components?

• Backend API: ../geogami-server
• Analytics dashboard: ../geogami-dashboard
• Virtual environment: ../geogami-virtual-environment-dev

---

Table of contents

• Tech stack
• Prerequisites
• Getting started
• Configuration
• Available scripts
• Project structure
• Building for mobile (iOS / Android)
• Internationalisation
• Contributing
• Map Features and Task Types in GeoGami
• Contact
• License

---

Tech stack

Area	Technology
Framework	Angular 12, Ionic 6
Native shell	Capacitor 3 (iOS, Android)
Maps	Leaflet, Mapbox GL
State / forms	Reactive forms, RxJS
UI components	Angular Material, Ionic Components
i18n	@ngx-translate/core
HTTP	Angular HttpClient (JWT bearer)

Prerequisites

• Node.js 14.x – 16.x (Angular 12 isn't compatible with newer Node versions)
• npm 6+ or yarn 1.x
• Ionic CLI: npm i -g @ionic/cli
• For mobile builds:
  • iOS: macOS, Xcode 14+, CocoaPods
  • Android: Android Studio with SDK 33+

Getting started

git clone <repo-url>
cd geogami-ui
npm install
ionic serve         # opens http://localhost:8100

The dev server proxies API calls to the URL configured in src/environments/environment.ts.

Configuration

Per-environment configuration lives in src/environments/:

File	Used when
environment.ts	ionic serve, dev builds
environment.prod.ts	ionic build --prod

Typical values:

export const environment = {
  production: false,
  apiURL: 'http://localhost:3000',         // GeoGami server
  dashboardURL: 'http://localhost:3838',   // Shiny dashboard
  mapboxAccessToken: '<your-mapbox-token>',// Required for Mapbox GL map rendering

  // Virtual environment (only required for virtual-world games)
  uiURL: 'http://localhost:8100',          // UI origin used by the embedded WebGL view
  webglURL: 'http://localhost:50544'       // Unity WebGL build served locally
};

Available scripts

Command	Purpose
npm start / ionic serve	Run dev server with live reload
npm run build	Build the web bundle into www/
npm run build-browser	Production browser build
npm test	Run Karma unit tests
npm run lint	TSLint check
ionic capacitor sync ios	Copy www/ into the iOS Xcode project
ionic capacitor sync android	Copy www/ into the Android Studio project

Project structure

src/app/
├── pages/
│   ├── play-game/           # Real-world & virtual game playback
│   ├── create-game/         # Author new games (real + VR)
│   ├── edit-game/           # Modify existing games
│   ├── analyze-game/        # Track listing + dashboard launcher
│   ├── multiplayer/         # Real-time multiplayer flows
│   ├── user/                # Login, register, profile, verify-email,
│   │                        # reset-password, user-management (admin)
│   ├── showroom/            # Map / task / world demos
│   └── handbook/            # In-app help
├── services/                # AuthService, UtilService, …
├── models/                  # TypeScript interfaces and shared models
└── interceptors/            # JWT refresh handling

Building for mobile (iOS / Android)

ionic capacitor build ios       # opens the Xcode project
ionic capacitor build android   # opens Android Studio

The ios/ and android/ folders are tracked in this repo so push notifications, plugins, and signing settings stay reproducible.

Internationalisation

Translation files live at src/assets/i18n/<locale>.json. Currently shipped: en, de, fr, pt, ar. Add a new key under the appropriate namespace; the UI uses Angular | translate pipes everywhere, including dynamic strings such as toasts.

Contributing

• Branch from dev (PRs target master), open a PR, and reference an issue when applicable.
• Please run npm run lint and the unit tests before pushing.
• Bug reports and feature requests: https://github.com/geogami-team/geogami/issues.

---

Map Features and Task Types in GeoGami

The sections below describe the gameplay primitives the UI exposes — useful both for new players and for contributors implementing changes to game authoring or playback.

Task types

GeoGami groups task types into Navigation tasks and Thematic tasks, plus a standalone Information module that lets game creators give the player hints, rules, or context before play.

Navigation tasks

Navigation tasks direct the player to a new location.

Navigation to flag	Navigation with arrow	Navigation via text	Navigation via photo

Thematic tasks

Thematic tasks are location-specific tasks that probe specific spatial skills.

Self-location	Object location	Direction determination	Free task

Free tasks

Free tasks let game creators freely combine question and answer types to build quizzes or custom thematic challenges.

Supported question types

Type	Description
TEXT	Plain text question
MAP_FEATURE	Question referencing a map feature
MAP_FEATURE_FREE	Free-form map-feature question
MAP_FEATURE_PHOTO	Map-feature question with a photo
MAP_TARGET	Question targeting a specific map location
MAP_DIRECTION	Question about a map direction
MAP_DIRECTION_MARKER	Direction question shown via a map marker
MAP_DIRECTION_PHOTO	Direction question shown via a photo
NAV_INSTRUCTION	Navigation instruction prompt
NAV_INSTRUCTION_PHOTO	Navigation instruction shown via a photo
PHOTO	Photo-based question
INFO	Informational prompt (no question)

Supported answer types

Type	Description
POSITION	Player provides their current position
MAP_POINT	Player picks a point on the map
DIRECTION	Player indicates a direction
MAP_DIRECTION	Player indicates a direction on the map
PHOTO	Player submits a photo
DRAW	Player draws on the map
MULTIPLE_CHOICE	Multiple-choice answer
MULTIPLE_CHOICE_TEXT	Multiple-choice with text options
TEXT	Free-text answer
NUMBER	Numeric answer
INFO	Informational acknowledgement (no answer)

Map features

Each task can be configured with a combination of map settings and marker / overlay settings.

Map settings

Setting	Options
Zoom	manual · zoom to task · zoom to game · off
Map Section	movable · automatically-centered · static
Map Rotation	manual · automatic · automatic on-demand · fixed to north
Map Type	standard · map selection · satellite · satellite on-demand · satellite swipe · 3D · 3D on-demand · blank · blank + satellite swipe
Reduced Information	strips non-essential map details to test orientation in minimal-information settings
Switch Layer (virtual worlds)	toggles between map material and satellite layer inside the Unity virtual environment

Marker / overlay settings

Setting	What it does	Modes
Location Marker	Shows the player's current position	on · on-demand · at start of task · off
View Direction Marker	Shows the device's current heading	on · on-demand · at start of task · off
Track Recording	Records the player's route	for the entire game · for the current task · also for the next task
Buffer	Reveals a circular section of the map around the player	configurable diameter, 20–100 m
Highlight Landmarks	Highlights landmarks near the destination (with optional explicit landmarkFeatures list)	on · off
Highlight Street Section	Highlights the street segment at the destination	on · off

Game environments

GeoGami games can be played in two environments:

• Real world — outdoor play using the device's GPS and compass.
• Virtual world — indoor / remote play in a Unity-based 3D environment.

Both environments support single-player and multiplayer modes, with the same task and map-feature catalogue.

---

Contact

Spatial Intelligence Lab (SIL) — Institute for Geoinformatics, University of Münster

Address	Heisenbergstraße 2, 48149 Münster
Email	geogami(at)uni-muenster.de
Website	https://geogami.ifgi.de
Team	https://geogami.ifgi.de/kontakt.html#team

License

GeoGami is published under the MIT License. © 2026 — GeoGami. See the root project for full attribution and citation information.