<!-- GeoAIGames documentation, version 2.3.0. All sections in order; "What's New in This Version" is the last section. -->

# GeoAIGames Documentation

This is the official documentation for **GeoAIGames, version 2.3.0**. It describes how the game works, how points are calculated, how levels are unlocked and how player data is handled.

Version 2.3.0 is the **initial documentation release**. It documents everything that is implemented in the game at this version. Earlier releases did not have public documentation; their history is summarized in the [changelog](../../changelog/index.md).

## Who this documentation is for

- **Players** who want to understand the rules, the scoring and how to unlock levels.
- **The GeoAIGames AI Assistant** and other AI systems that answer questions about the game. Every page is plain Markdown with explicit rules and can be read on its own.

## Sections

| Section | What it covers |
|---|---|
| [Game Overview](game-overview.md) | What GeoAIGames is, who it is for, platforms and the general flow of play |
| [Game Rules and Conditions](game-rules.md) | How to start, answer, finish and leave a game; restrictions |
| [Scoring System](scoring-system.md) | Points per answer, streak bonuses, level multipliers, examples |
| [Levels and Stages](levels-guide.md) | The five levels, unlock thresholds, player level, difficulty |
| [Game Features](game-features.md) | Sign-in, Telegram integration, screens, map controls, progress tracking |
| [FAQ](faq.md) | Frequently asked questions |
| [User Statistics](user-statistics.md) | Total score, best scores, progress indicators; personal versus public information |
| [Privacy and Security](privacy-and-security.md) | Authentication, stored data, access restrictions |
| [What's New in This Version](whats-new.md) | Changes in version 2.3.0 |

## Key facts at a glance

| Fact | Value in version 2.3.0 |
|---|---|
| Where to play | Telegram Mini App: `t.me/geoaigames_bot/play` |
| Number of levels | 5 |
| Rounds per game | 10 |
| Points per correct answer (base) | 10 (Level 1 Hard: 20) |
| Level multipliers | Level 1 ×1, Level 2 ×2, Level 3 ×3, Level 4 ×4, Level 5 ×5 |
| Unlock thresholds (lifetime score) | Level 2: 1,000 · Level 3: 3,000 · Level 4: 6,000 · Level 5: 10,000 |
| Time limits | None |
| Interface language | English |

## How to read version information

- Each page states the game version it describes and the date it was last updated.
- The documentation for every released version is kept unchanged at its own address (`/versions/v2.3.0/`). The address `/latest/` always shows the version that is currently deployed.
- The final section of every version is [What's New in This Version](whats-new.md).

# Game Overview

## What is GeoAIGames?

GeoAIGames is a geography learning game. It is played mainly as a **Telegram Mini App**: a small app that opens inside Telegram. The name is also written "Geo AI Games".

The game started as **Atlas Quest**, a ten-round quiz about country shapes. Atlas Quest is now **Level 1 · Atlas Explorer** of a five-level game. Levels 2 to 5 cover water, landforms, natural resources and mixed geography topics.

## Game concept and objectives

- **Learn by playing.** After every answer in Levels 2–5, the game shows a short explanation and names its source.
- **Answer on a real map.** Many questions are answered by tapping countries on a world map.
- **Collect points to progress.** Points from every game add up to a lifetime score. Higher scores unlock higher levels, and higher levels multiply their points (×1 to ×5).
- **Verified facts.** Questions are built from a reviewed knowledge base. Every fact has a source. Statistics state their year and whether they describe production, reserves or resources.

## Target audience

- **Primary:** Telegram users, from curious teenagers to adults, who want a short geography game they can play in a few minutes.
- **Secondary:** students and teachers who want sourced geography facts in a playful format.

## Main gameplay concept

Every game has **10 rounds**. In each round the player answers one question. A correct answer earns points; consecutive correct answers add a small streak bonus. When the game ends, the result is saved to the player's profile and added to their lifetime score.

| Level | Name | Theme | Multiplier |
|---|---|---|---|
| 1 | Atlas Explorer | Countries: find them on the map and name them by their shape | ×1 |
| 2 | Hydro Explorer | Rivers, lakes, waterfalls, seas, oceans, straits and canals | ×2 |
| 3 | Earth Explorer | Mountain ranges, peaks, passes, valleys, volcanoes, canyons, tunnels | ×3 |
| 4 | Resource Explorer | Minerals and deposits; production versus reserves | ×4 |
| 5 | Master Explorer | Climate, regions, population, trade, shipping routes and combined facts | ×5 |

Details: [Levels and Stages](levels-guide.md).

## Supported platforms

| Platform | What works |
|---|---|
| Telegram (Mini App) | The full game: sign-in, all five levels, saved progress. Open `t.me/geoaigames_bot/play`. |
| A regular web browser (outside Telegram) | Level 1 only. There is no sign-in, so nothing is saved to a profile; best scores are kept on the device. Levels 2–5 show "Open GeoAIGames in Telegram to unlock". |

- The interface is mobile first and also works with a mouse on desktop.
- The interface language is English.
- A separate, older **Web Game** also exists. It is not part of the five levels and does not save progress to a profile. See [Game Features](game-features.md#web-game).

## General gameplay flow

1. **Open** the Mini App from Telegram. The app signs the player in automatically with their Telegram account.
2. **Level Selection** (home screen) shows the player's name, lifetime score and player level, and five level cards.
3. **Choose a level.** Locked levels show how many points are still needed.
4. **Introduction screen.** Level 1: choose Easy or Hard, then Play. Levels 2–5: read the categories and rules, then Start game.
5. **Play 10 rounds.** After each answer the correct answer is shown.
6. **Result screen:** correct answers, points, best streak, best score, and any level that was just unlocked. The player can play again, challenge a friend or return to the menu.

## Terminology

These terms are used with the same meaning on every page.

| Term | Meaning |
|---|---|
| Game (session) | One play-through of a level: 10 rounds from start to result screen. |
| Round | One question inside a game. |
| Level | One of the five themed parts of the game (Level 1 to Level 5). |
| Mode | A variant of a level. Level 1 has two modes, Easy and Hard. Levels 2–5 have one mode each. |
| Base score | Points before the level multiplier is applied. |
| Level multiplier | The factor (×1 to ×5) applied to the base score of a level. |
| Streak | The number of consecutive fully correct answers in the current game. |
| Streak bonus | Extra points for a correct answer that continues a streak. |
| Lifetime score | The sum of the scores of all saved games of a player, in all levels. Also called "total score" and shown as "Score". |
| Player level | The highest level up to which every level is unlocked. Shown as "Level" next to the player's name. |
| Best score | The highest score of a single game, kept per mode and per level. |
| Mastery | For Levels 2–5: how many of the level's questions the player has answered fully correctly at least once. |
| Unlock | Making a level playable. Unlocks are permanent. |

# Game Rules and Conditions

## General game rules

1. Every game has exactly **10 rounds**. Each round is one question.
2. Each round can be answered **once**. An answer cannot be changed after it is given.
3. Rounds are played **in order**. A round cannot be skipped.
4. The **server decides** whether an answer is correct and how many points it is worth. The app only displays the result.
5. A level can be played only after it is **unlocked**. Level 1 is always unlocked. See [Levels and Stages](levels-guide.md#unlocking-levels).
6. There are **no lives** and no early game over. A game always runs all 10 rounds.

## How to start a game

1. Open the Mini App in Telegram (`t.me/geoaigames_bot/play`). Inside Telegram the game opens only after a successful sign-in.
2. On the Level Selection screen, tap an unlocked level card.
3. **Level 1:** choose **Easy · big countries** or **Hard · all countries**, then tap **Play**.
4. **Levels 2–5:** read the introduction (categories and rules), then tap **Start game**.

If a level is locked, tapping its card shows how to unlock it, for example "Reach 3,000 total points to unlock".

## How to complete a task (answering a round)

### Level 1 · Atlas Explorer

Rounds alternate between two task types. Round 1 is "Find it", round 2 is "Name it", and so on.

| Task | What the player sees | How to answer |
|---|---|---|
| **Find it** | The name of a country and a map zoomed to its area | Tap that country on the map |
| **Name it** | A highlighted country on the map | Choose its name from 4 options (the other options are nearby countries) |

### Levels 2–5 · Question engine

Each question has an answer mode:

| Answer mode | How to answer |
|---|---|
| Options (one answer) | Tap one option. |
| Options (several answers) | Tap every correct option, then tap **Check**. |
| True / False | Tap True or False. |
| Map, one country | Tap one country on the map. |
| Map, several countries | Tap every correct country, then tap **Check**. |
| Matching | Match each item on the left with one item on the right, then tap **Check**. |

## Correct and incorrect answers

- **Correct:** the app shows "Correct! +N" with the points earned. The streak continues.
- **Incorrect:** the answer scores 0 points and the streak resets to 0.
  - Level 1 "Find it": the tapped country is shown in red with its name; the correct country is shown in green.
  - Level 1 "Name it": the correct option is marked; the wrong choice is marked as wrong.
- **Partly correct** (Levels 2–5, questions with several answers or matching only): the app shows "Partly right · +N". Partial points are awarded, there is no streak bonus, and the streak resets. See [Scoring System](scoring-system.md#partial-answers-levels-25).
- After every answer in Levels 2–5 the map shows the correct countries in green, wrong picks in red and missed countries in light green. The app shows an explanation and the source of the fact.
- Some correct answers are countries that are too small to tap on the world map. In that case the app names them after the answer ("Also: …, too small for this map").

## Time limits

There are **no time limits** in version 2.3.0. There is no countdown and no time bonus. The server records how long each answer took (Levels 2–5) for statistics only; it does not affect points.

## Game restrictions

- **Sign-in required in Telegram.** Inside Telegram, a game can start only when the player is signed in.
- **Locked levels cannot be played.** The server refuses to start a game in a locked level, even if the app is modified.
- **One unfinished game per game type.** Starting a new game closes any earlier unfinished game of the same type as abandoned. Abandoned games earn no points.
- **Level 1 results are checked.** The Level 1 game runs in the app, and the server checks that the submitted score is possible for the number of correct answers under the rules of the selected mode. An impossible score is rejected and not saved.
- **No double counting.** A finished game is saved once. Submitting it again adds no points.
- **Levels 2–5:** every round must be answered before the game can be finished.
- **Session length:** 10 rounds in every level. Players cannot choose another length in this version.

## Completion conditions

A game is complete when all 10 rounds are answered and the result screen appears. The app then saves the result to the player's profile:

- "☁️ Saved to your profile" means the result was saved. Its points are added to the lifetime score, and level unlocks are checked immediately.
- The lifetime score and player level next to the player's name are updated after every saved game.

A **level** counts as completed after at least one finished game in that level. The Level 1 card shows "Completed"; the cards of Levels 2–5 show mastery progress instead. Completion is for information only; it does not unlock other levels in this version.

## Failure conditions

There is no losing state: a game cannot be lost or ended early by wrong answers. A game ends **without points** in these cases:

| Situation | Result |
|---|---|
| The player presses Telegram's Back button during a game | The game is abandoned. No result is saved. |
| The player starts another game before finishing the current one | The earlier game is abandoned. |
| The result cannot be saved (no connection) in Levels 2–5 | The app shows "Couldn't save this game" with **Try again**. Tapping Try again sends the result again. |
| The result cannot be saved in Level 1 | The app shows "Couldn't save this game to your profile". The score still counts as a best score on the device, but it is not added to the lifetime score. |
| The sign-in has expired | The app shows "Session expired". Close the Mini App and open it again from the bot. |

## User responsibilities

GeoAIGames has no separate terms of service in version 2.3.0. To make sure progress is recorded correctly, the player should:

- Open the game from Telegram to have progress saved to their profile.
- Wait for "Saved to your profile" on the result screen before closing the app.
- Reopen the Mini App from the bot when the app reports that the session has expired.

# Scoring System

All points are calculated **on the GeoAIGames server**. The app never decides the multiplier or whether an answer is correct.

## How scores are calculated

The general rule for every answer is:

```
final points = round((base points × answer fraction + streak bonus) × level multiplier)
```

- **Base points:** 10 for a correct answer (20 in Level 1 Hard).
- **Answer fraction:** 1 for a fully correct answer, 0 for a wrong answer, or a value between 0 and 1 for a partly correct answer (Levels 2–5 only).
- **Streak bonus:** extra points for a correct answer that continues a streak. Only fully correct answers get a streak bonus.
- **Level multiplier:** ×1 to ×5, depending on the level the game is played in. It is applied once, after the base points and the streak bonus.

## Points per correct answer

The streak is the number of consecutive fully correct answers including the current one (the first correct answer has streak 1).

| Mode | Points for a correct answer (before the multiplier) | Maximum streak bonus | Perfect 10-round game (before the multiplier) |
|---|---|---|---|
| Level 1 Easy | `10 + min(5, streak − 1)` | 5 | 135 |
| Level 1 Hard | `20 + min(10, 2 × (streak − 1))` | 10 | 270 |
| Levels 2–5 | `10 + min(5, streak − 1)` | 5 | 135 |

Points for consecutive correct answers:

| Correct answer in a row | 1st | 2nd | 3rd | 4th | 5th | 6th and later |
|---|---|---|---|---|---|---|
| Easy and Levels 2–5 | 10 | 11 | 12 | 13 | 14 | 15 |
| Level 1 Hard | 20 | 22 | 24 | 26 | 28 | 30 |

Level 1 Hard always gives exactly twice the points of Easy for the same answers.

## Penalties

- A **wrong answer** scores 0 points and resets the streak to 0.
- Points are **never subtracted** from a score. There are no negative points.
- In questions with several answers, **wrong picks reduce** the partial points for that question (see below).

## Bonuses

- **Streak bonus:** see the tables above.
- **Level multiplier:** see below.
- There is **no time bonus** in version 2.3.0.

## Partial answers (Levels 2–5)

Questions with several correct answers (several options, several countries on the map) and matching questions give partial points.

| Question kind | Answer fraction |
|---|---|
| Several answers (options or countries) | `max(0, (correct picks − wrong picks) ÷ number of correct answers)` |
| Matching | `correct pairs ÷ total pairs` |

The base points of a partial answer are `round(10 × answer fraction)`. A partial answer gets **no streak bonus** and **resets the streak**. An answer counts as correct only when the fraction is 1.

## Level multipliers

| Level | Multiplier | One correct answer without bonus | Perfect game |
|---|---|---|---|
| 1 Atlas Explorer | ×1 | 10 (Hard: 20) | 135 (Hard: 270) |
| 2 Hydro Explorer | ×2 | 20 | 270 |
| 3 Earth Explorer | ×3 | 30 | 405 |
| 4 Resource Explorer | ×4 | 40 | 540 |
| 5 Master Explorer | ×5 | 50 | 675 |

- The multiplier belongs to the level the game is **played in**.
- The rules and the multiplier are fixed when a game starts. A rule change by the game team never changes a game that is already running or finished.

## Score aggregation

- **Game score:** the sum of the final points of all 10 rounds.
  - Levels 2–5: each answer is scored and multiplied when it is submitted.
  - Level 1: the game is played in the app; at the end the server checks the base score and multiplies it by ×1.
- **Lifetime score:** the sum of the scores of all saved games of the player, in every level and mode. It is calculated from the saved results every time it is shown, so it cannot drift. Abandoned games do not count.
- **Best score:** the highest single-game score, per mode and per level (Level 1: the higher of Easy and Hard).

### Results from earlier versions

Version 2.1.0 divided all point values by 10. Results saved before version 2.1.0 are **counted as one tenth** of their stored value in the lifetime score and in best scores. For example, a perfect Easy game saved before 2.1.0 was stored as 1,350 points and counts as 135. Stored results are never changed.

## Result calculation (end of a game)

The result screen shows:

- correct answers out of 10 (only fully correct answers count),
- the game score (in Levels 2–5 with the multiplier, for example "points (×2)"),
- the best streak of the game,
- the best score ever in this mode or level,
- "New best score!" when the game beats the previous best.

## Examples of score calculations

**Example 1: Level 1 Easy, three correct answers in a row, then a wrong one.**
10 + 11 + 12 + 0 = **33 points**. After the wrong answer the streak is 0, so the next correct answer is worth 10 again.

**Example 2: a perfect Level 1 Easy game.**
10 + 11 + 12 + 13 + 14 + 15 + 15 + 15 + 15 + 15 = **135 points**. Level 1 Hard: **270 points**.

**Example 3: Level 2 (×2), first two answers correct.**
Round 1: (10 + 0) × 2 = **20**. Round 2: (10 + 1) × 2 = **22**.

**Example 4: Level 2 (×2), a question with 3 correct countries.**

| Picks | Fraction | Base points | Final points |
|---|---|---|---|
| 3 correct, 0 wrong | 1 | 10 + streak bonus | (10 + bonus) × 2 |
| 2 correct, 0 wrong | 2 ÷ 3 | round(6.67) = 7 | 7 × 2 = **14** |
| 2 correct, 1 wrong | (2 − 1) ÷ 3 | round(3.33) = 3 | 3 × 2 = **6** |
| 1 correct, 2 wrong | 0 (never below 0) | 0 | **0** |

**Example 5: Level 3 (×3), a matching question with 4 pairs, 3 matched correctly.**
Fraction 3 ÷ 4; base points round(7.5) = 8; final points 8 × 3 = **24**. The streak resets.

**Example 6: a perfect Level 5 game.**
Base 135 × 5 = **675 points**.

**Example 7: unlocking.**
A player with a lifetime score of 940 finishes a Level 1 Easy game with 70 points. The new lifetime score is 1,010, so Level 2 unlocks immediately (threshold 1,000). See [Levels and Stages](levels-guide.md#unlocking-levels).

# Levels and Stages

GeoAIGames has **five levels**. All five level cards are visible from the start; Level 1 is unlocked for everyone, and the other levels unlock with the player's lifetime score.

| Level | Name | Multiplier | Unlocks at (lifetime score) | Questions in this version |
|---|---|---|---|---|
| 1 | Atlas Explorer | ×1 | always unlocked | generated from the world map |
| 2 | Hydro Explorer | ×2 | 1,000 | 110 |
| 3 | Earth Explorer | ×3 | 3,000 | 20 |
| 4 | Resource Explorer | ×4 | 6,000 | 20 |
| 5 | Master Explorer | ×5 | 10,000 | 18 |

There is no Level 6 in version 2.3.0.

## Unlocking levels

- Levels unlock by **lifetime score**: the total of all saved games in all levels (see [Scoring System](scoring-system.md#score-aggregation)). It is not the score of a single game.
- Unlocks are checked **after every saved game**, at the same moment the result is saved. A newly unlocked level is announced on the result screen ("🔓 Level 2 · Hydro Explorer unlocked!").
- Unlocks are **permanent**. A level never locks again.
- Points earned in higher levels count more because of the multiplier, so progress speeds up.
- A locked card shows the progress towards its threshold, for example "🔒 1,095 / 3,000 points" with a progress bar.
- The server enforces unlocks. A locked level cannot be started from a modified app.
- In a regular web browser (outside Telegram) there is no sign-in, so Levels 2–5 stay locked and show "Open GeoAIGames in Telegram to unlock".
- The game team can unlock a level for a specific player manually.

## Player level

The **player level** is the highest level N such that every level from 1 to N is unlocked. It is shown next to the player's name, for example "Ana (Score: 1,095 | Level: 2)".

- Every new player starts at player level 1.
- The player level **never goes down**.
- The player level is stored in the player's profile, so it is the same on every device.

## Level completion

A level is completed after **at least one finished game** in that level. Completion is shown on the level card. It does not affect unlocking in this version.

## Difficulty progression

- **Across levels:** later levels cover more specialized topics and combine several facts. Their multipliers are higher (×1 to ×5).
- **Level 1:** the player chooses Easy or Hard (see below).
- **Levels 2–5:** each question has a difficulty from 1 to 3. Games mix all three difficulties. Players cannot choose a difficulty, and difficulty does not adapt to the player in this version.
- **Repeats:** Levels 2–5 avoid questions the player has seen recently. When a level has few questions, repeats can still happen.

## Level 1 · Atlas Explorer (×1)

The original Atlas Quest game.

- **Categories:** country identification, country shapes, geographic position, neighbours and borders. Neighbouring countries are used as the wrong options; there are no separate questions about borders.
- **Rounds:** 10, alternating "Find it" (tap the named country on a zoomed map) and "Name it" (choose the highlighted country from 4 options).

| Mode | Countries used | Wrong options in "Name it" | Points per correct answer |
|---|---|---|---|
| Easy · big countries | the 75 largest countries of the quiz | chosen from the 4 nearest countries | 10 + streak bonus up to 5 |
| Hard · all countries | all countries of the quiz (some territories and very small countries are not used) | chosen from the 6 nearest countries | 20 + streak bonus up to 10 |

- Hard also uses a tighter map zoom.
- Level 1 is the only level that can be played outside Telegram (without saving progress).
- **Special rule:** the Level 1 game runs inside the app. The server checks the final score for plausibility; it does not score each answer individually.

## Level 2 · Hydro Explorer (×2)

Water on the map: rivers, lakes, waterfalls, seas, oceans, straits and canals.

- **Categories with questions:** Rivers, Lakes, Waterfalls, Seas, Oceans, Straits, Canals.
- **Categories without questions yet:** River basins (shown as "soon" on the introduction screen).
- **Question examples:** identify a highlighted river or lake; select every country a river flows through; which seas a strait connects; warm and cold ocean currents; deepest trenches and lakes; match rivers with their mouths.
- **Map layers:** Rivers and Lakes buttons show background layers.

## Level 3 · Earth Explorer (×3)

Landforms.

- **Categories with questions:** Mountain ranges, Mountain peaks, Mountain passes, Valleys, Volcanoes, Canyons, Tunnels.
- **Categories without questions yet:** Mountain roads ("soon").
- **Question examples:** countries crossed by a mountain range; where a peak or volcano is; which range contains a peak; well-known passes and tunnels.

## Level 4 · Resource Explorer (×4)

Natural resources and where they are produced.

- **Categories with questions:** Gold, Copper, Iron ore, Oil, Lithium, Cobalt, Diamonds, Other minerals.
- **Categories without questions yet:** Natural gas, Coal ("soon").
- **Data source:** USGS Mineral Commodity Summaries 2026 (production year 2024; reserves and resources as published in 2026).
- **Special rule:** questions always state whether a figure is **mine production**, **reserves** or **identified resources**. These are different measures; for example, the country that mines the most of a mineral is not always the country with the largest reserves.

## Level 5 · Master Explorer (×5)

Mixed challenges that combine several facts.

- **Categories with questions:** Climate zones, Natural regions, Deserts & forests, Population density, Economic geography, Trade routes, Shipping routes, Strategic straits & canals, Complex relationships.
- **Categories without questions yet:** Megacities ("soon").
- **Question examples:** what strategic straits connect; a shipping route through several straits; countries that have both a given mountain range and a given river basin; population and export figures (World Bank, 2024 data).

## Question types (Levels 2–5)

| Type | Player action | Partial points |
|---|---|---|
| Single choice | pick one option | no |
| Multiple choice | pick all correct options, then Check | yes |
| True / False | True or False | no |
| Map identification | tap the country on the map | no |
| Country identification | name a highlighted country, or tap it | no |
| Object identification | a river, lake or marked place is shown; pick its name | no |
| Geographic relationship | select every related country on the map, then Check | yes |
| Resource identification | tap the producing country, or pick the mineral of a mine | no |
| Matching | match each item on the left to one on the right | yes |

# Game Features

This page lists the features that exist in version 2.3.0. Features that do not exist yet are listed at the end.

## User registration and authentication

- **Telegram only.** There is no separate account, password or e-mail registration.
- When the Mini App opens inside Telegram, it signs the player in automatically. The first sign-in creates the player's profile; later sign-ins update the name and photo from Telegram.
- During sign-in the app shows "Starting…". If sign-in fails:
  - "Try again" appears when the server cannot be reached.
  - "Close" appears when Telegram's launch data is invalid or too old. Reopen the Mini App from the bot.
- The sign-in renews itself while the app is open. If renewal is no longer possible, the app shows "Session expired"; reopening the Mini App from the bot fixes it.

Security details: [Privacy and Security](privacy-and-security.md).

## Telegram integration

| Feature | What it does |
|---|---|
| Mini App | The game opens inside Telegram at `t.me/geoaigames_bot/play`. |
| Automatic sign-in | Uses the signed launch data that Telegram gives the Mini App. |
| Theme colours | The app uses the colours of the player's Telegram theme (light or dark). |
| Back button | Telegram's Back button returns to the Level Selection screen. During a game it abandons the game. |
| Haptic feedback | Short vibrations for taps, correct answers, wrong answers and unlocks (on devices that support it). |
| Device best scores | Level 1 best scores are also kept in Telegram's cloud storage for the Mini App, or in the browser outside Telegram. |
| Challenge a friend | The result screen opens Telegram's share dialog with a message and the game link. |

The share message contains the result, for example "I found 8/10 countries (98 pts) in Atlas Quest. Can you beat me?" (Level 1) or "I scored 270 points in Hydro Explorer on GeoAIGames. Can you beat me?" (Levels 2–5). The message is sent only if the player chooses a chat and sends it.

## Game interface

| Screen | Contents |
|---|---|
| Sign-in | Shown while the app signs in, or when sign-in fails. |
| Level Selection (home) | The player's name with lifetime score and player level, and five level cards. A line shows whether progress is saved ("☁️ Progress is saved to your profile"). |
| Level card | Level number, icon, name, multiplier, short description (or the unlock hint when locked), best score, a progress bar and a Play label. Locked cards show the points needed. |
| Level 1 introduction | Easy/Hard choice, an animated map preview, best score, the points rule of the selected mode, Play. |
| Levels 2–5 introduction | Description, categories ("soon" for categories without questions), rules, best score, Start game. |
| Game | Round dots (green correct, red wrong), streak badge (🔥 from 2 correct in a row), current points, the map, and the answer panel. |
| Result | Correct answers out of 10, a message, points, best streak, best ever, "New best score!", newly unlocked level, Play again, Challenge a friend, Menu. |

## Navigation

- Tap a level card to open its introduction screen.
- **Menu** on the result screen and Telegram's **Back** button return to Level Selection.
- **Next** moves to the next round after an answer; on the last round the button says **Results**.

## Maps and geographical interactions

- The map is an interactive world map of countries (source: Natural Earth).
- **Answering on the map:** tap a country to answer; in multi-select questions, tap countries to select or unselect them, then tap Check.
- **Background layers (Levels 2–5):** the **Rivers** and **Lakes** buttons turn river and lake layers on and off. Layers load only when they are first needed.
- **Re-centre (Levels 2–5):** the **⤢** button returns the map to the question's view.
- **Reveal after answering:** correct countries in green, wrong picks in red, missed countries in light green, with labels. A river, lake or marked place is highlighted and named.
- Very small countries (micro-states) cannot be tapped on this world map.

## Zoom and touch controls

| Control | Level 1 | Levels 2–5 |
|---|---|---|
| Tap with one finger | answers | answers |
| Drag with one finger | no effect (one finger only taps) | moves the map |
| Pinch with two fingers | zooms (since version 2.3.0) | zooms |
| Drag with two fingers | moves the map (since version 2.3.0) | moves the map |
| Mouse wheel (desktop) | no effect | zooms |
| Mouse drag (desktop) | no effect | moves the map |

- A pinch or drag never counts as an answer.
- Zooming keeps the point between the fingers in place.
- The map cannot be zoomed out too far or moved out of sight.
- In Level 1, every new round starts from its own zoomed view of the right area.

## Progress tracking

- **Lifetime score and player level** next to the player's name, updated after every saved game.
- **Best score** per level card and on introduction screens.
- **Progress bar** on each card: mastery for Levels 2–5 ("12/110 mastered"), completion for Level 1.
- **Unlock progress** on locked cards ("🔒 1,095 / 3,000 points").
- **Explanations and sources** after every answer in Levels 2–5. The app shows "Source:" with the name of the source and, for statistics, the year of the data.

Details: [User Statistics](user-statistics.md).

## Playing outside Telegram

In a regular web browser the game opens without sign-in. Only Level 1 can be played, and best scores are saved on the device only. The home screen shows "Open in Telegram to save your progress".

## Web Game

A separate, older browser game exists alongside the Mini App. It has five expeditions (countries, capitals and big cities, rivers/lakes/seas, mountains and relief, and a border journey). It keeps scores only on the device and is not connected to the five levels, the lifetime score or the player profile.

## Features not available in version 2.3.0

These features do **not** exist in this version. They must not be described as available.

- Achievements and badges.
- Leaderboards, rankings and public player profiles.
- A statistics screen in the app (the server records statistics, but the app does not show them yet).
- Time limits, timed rounds and time bonuses.
- Choosing the number of rounds (always 10).
- Choosing the difficulty in Levels 2–5, or difficulty that adapts to the player.
- Daily challenges and friend duels.
- AI hints. Answers are never checked by AI.
- Interface or questions in languages other than English.
- Deleting a profile from within the app.

# FAQ

## Playing

### How do I start playing?

Open `t.me/geoaigames_bot/play` in Telegram. The game signs you in with your Telegram account automatically. Tap the Level 1 card, choose Easy or Hard, and tap Play. See [Game Rules and Conditions](game-rules.md#how-to-start-a-game).

### Do I need to create an account?

No. Your Telegram account is your GeoAIGames account. There is no separate registration, password or e-mail.

### How can I connect my Telegram account?

You don't need to do anything. Opening the Mini App inside Telegram connects your Telegram account automatically. The first time you open it, your profile is created.

### Can I play without Telegram?

Yes, but only Level 1. In a regular web browser there is no sign-in, so your progress is not saved to a profile and Levels 2–5 stay locked. Best scores are kept on that device.

### How many rounds does a game have?

Always 10 rounds.

### Is there a time limit?

No. You can take as long as you need for each answer. There is no time bonus either.

### Can I change my answer?

No. Each round can be answered once.

### What is the difference between Easy and Hard in Level 1?

Easy uses the 75 largest countries and a wider map view. Hard uses all countries of the quiz, more look-alike neighbours and a tighter map view. Hard gives twice the points: 20 per correct answer instead of 10, and a streak bonus of up to 10 instead of 5.

### How do I zoom the map?

Pinch with two fingers. In Level 1, two fingers zoom and move the map, and one finger only taps. In Levels 2–5 you can also drag with one finger, use the mouse wheel on a computer, and tap ⤢ to return to the question's view. See [Game Features](game-features.md#zoom-and-touch-controls).

### A country is too small to tap. What can I do?

Zoom in with two fingers. Very small countries (micro-states) cannot be tapped on the world map at all. When one of them is part of a correct answer, the app names it after you answer.

### What happens if I leave a game in the middle?

The game is abandoned and earns no points. Pressing Telegram's Back button during a game, or starting another game, abandons the current one.

## Score and levels

### How are points calculated?

A correct answer is worth 10 points (20 in Level 1 Hard), plus a streak bonus for consecutive correct answers, multiplied by the level multiplier (×1 to ×5). A wrong answer is worth 0 points. See [Scoring System](scoring-system.md).

### What is the streak bonus?

Each correct answer in a row adds one more point, up to 5 extra points (Level 1 Hard: two more points, up to 10). A wrong or partly correct answer resets the streak.

### Why did I get only some of the points?

In questions with several correct answers or with pairs to match, you get points for the part you got right. Wrong picks reduce these points. Partial answers have no streak bonus. See [Scoring System](scoring-system.md#partial-answers-levels-25).

### How do I unlock the next level?

Collect lifetime points: 1,000 for Level 2, 3,000 for Level 3, 6,000 for Level 4 and 10,000 for Level 5. Points from every game in every level count. See [Levels and Stages](levels-guide.md#unlocking-levels).

### Do I have to complete a level to unlock the next one?

No. Only your lifetime score counts.

### Can a level become locked again?

No. Unlocks are permanent, and your player level never goes down.

### Where can I see my score?

Your lifetime score and player level are shown next to your name on the Level Selection screen, for example "Ana (Score: 1,095 | Level: 2)". Each level card shows your best score. The result screen shows the score of the game you just played.

### Why did my old scores become smaller?

Version 2.1.0 divided all point values by 10. Results from before version 2.1.0 count as one tenth of their original value. Your saved results were not changed; they are only counted on the new scale.

## Saving progress

### Why did my progress not update?

Check these causes:

1. **Not signed in.** Progress is saved only when the game runs inside Telegram and you are signed in. In a regular browser nothing is saved to a profile.
2. **The game was not finished.** Abandoned games earn no points.
3. **The result could not be saved.** If the result screen says "Couldn't save this game", tap Try again (Levels 2–5). In Level 1, a result that could not be saved is not added to your lifetime score.
4. **The session expired.** If the app says "Session expired", close the Mini App and open it again from the bot.

When a game is saved, the result screen shows "☁️ Saved to your profile" and your score next to your name is updated.

### Is my progress the same on all my devices?

Yes, if you play inside Telegram with the same Telegram account. Your lifetime score, unlocked levels, player level and best scores are stored in your profile on the GeoAIGames server.

### Can I reset or delete my profile?

Not from within the app in version 2.3.0.

## Other

### Who checks whether my answer is correct?

The GeoAIGames server, using a reviewed set of geographic facts. AI is never used to check answers.

### Where do the facts come from?

From named sources such as Natural Earth, Wikidata, Wikipedia, the U.S. Geological Survey and the World Bank. Every explanation names its source.

### Is there a leaderboard or achievements?

No. Leaderboards and achievements do not exist in version 2.3.0.

### In which languages is the game available?

English only, in version 2.3.0.

# User Statistics

This page explains the numbers GeoAIGames keeps about a player's games and where the player can see them.

## Statistics shown in the app

| Statistic | Where it is shown | Meaning |
|---|---|---|
| **Total score** ("Score") | Next to the player's name on Level Selection | The lifetime score: the sum of the scores of all saved games, in all levels. Used for unlocking levels. |
| **Player level** ("Level") | Next to the player's name | The highest level up to which every level is unlocked. |
| **Best score** | Each level card, introduction screens, result screen ("best ever") | The highest score of a single game. Level 1 shows the higher of Easy and Hard. |
| **Mastery** (Levels 2–5) | Level card, for example "12/110 mastered" | How many different questions of the level the player has answered fully correctly at least once, out of all questions of the level. |
| **Completion** (Level 1) | Level card: "Completed" or "Not completed" | Whether the player has finished at least one game in the level. |
| **Unlock progress** | Locked level cards, for example "🔒 1,095 / 3,000 points" | Lifetime score compared with the threshold of the level. |
| **Game result** | Result screen | Correct answers out of 10, game score, best streak, best score, new best, newly unlocked level. |

The total score and player level are refreshed after every saved game.

## Statistics recorded but not shown in the app

The server also records, for each player:

- the number of games played,
- correct and incorrect answers and accuracy (percentage of correct answers),
- the average time per answer (Levels 2–5),
- unlocked and completed levels,
- per level: games played, best score, accuracy, mastery,
- per category of Levels 2–5: questions answered, correct answers, accuracy and mastery.

There is **no statistics screen** in version 2.3.0, so players cannot view these numbers in the app yet.

## Achievements

There are no achievements in version 2.3.0.

## How the numbers are calculated

- Only **saved, finished games** count. Abandoned games count nowhere.
- The **total score** is recalculated from the saved results every time it is shown.
- Results saved before version 2.1.0 count as one tenth of their stored value (see [Scoring System](scoring-system.md#results-from-earlier-versions)).
- "Correct answers" counts only fully correct answers. Partly correct answers count as not correct for accuracy, but they still earn partial points.
- A game's result is saved once and never changed afterwards.

## Personal versus public information

| Information | Who can see it |
|---|---|
| Total score, player level, best scores, mastery, unlock progress, game results | **Only the player**, in their own app. |
| Statistics recorded on the server | Only the player's own account can request them from the server. The game team can access the database to operate the game. |
| A shared result ("Challenge a friend") | The people in the Telegram chat the player chooses to send it to. The message contains only the result text and the game link. |

There are **no public profiles, rankings or leaderboards** in version 2.3.0. No other player can see a player's name, score or statistics through the game.

This documentation never contains real player records or personal identifiers. Examples such as "Ana (Score: 1,095 | Level: 2)" are invented for illustration.

# Privacy and Security

This page describes how the GeoAIGames software handles player data in version 2.3.0. It is a technical description, not a legal privacy policy.

## User authentication

- Players sign in **only through Telegram**. GeoAIGames has no passwords.
- When the Mini App opens, Telegram gives it signed launch data. The app sends this data to the GeoAIGames server, which checks Telegram's cryptographic signature.
- The server accepts the launch data only if it is **recent** (by default, no older than 5 minutes). This limits replays of old launch data.
- The player's identity is taken **only from the verified Telegram data**. Any user ID sent in a request is ignored.
- After a successful check, the server issues a signed access token. The app keeps it **in memory only** (it is not written to the device's storage) and renews it automatically. By default a token is valid for 24 hours.
- If the token cannot be renewed, the app shows "Session expired" and the player reopens the Mini App.

## Personal data handling

### Data stored about a player

| Data | Source | Purpose |
|---|---|---|
| Telegram user ID | Telegram (verified launch data) | Identifies the player's account |
| Display name (first and last name, or username) | Telegram | Shown as the player's name in the app |
| Telegram username, profile photo link, language code, Premium status | Telegram | Profile information |
| Launch context (for example the type of chat the app was opened from) and the app platform and version | Telegram and the app | Technical and usage information |
| Time of registration and last sign-in | Server | Account management |
| Games: mode, start and end time, score, correct answers, best streak | Server | Scoring, unlocking, best scores |
| Answers in Levels 2–5: the answer given, correctness, points, response time | Server | Scoring and statistics |
| Level 1 game details: the countries asked and whether each answer was correct | The app | Game history |
| Level unlocks and player level | Server | Progression |

The name and photo are refreshed from Telegram at every sign-in.

### Data stored on the device

Level 1 best scores are also stored in Telegram's cloud storage for the Mini App (or in the browser's local storage outside Telegram), so that they are available offline.

### Data not collected

- No passwords, e-mail addresses or phone numbers are collected by GeoAIGames.
- The app loads no analytics or advertising scripts. The only external script is Telegram's official Mini App script.

## Public versus private information

- All game data is **private** to the player. There are no public profiles, rankings or leaderboards.
- Players can see only their own profile, sessions and statistics. The server rejects requests for another player's games.
- Sharing a result ("Challenge a friend") is optional. It opens Telegram's share dialog with a prepared message; nothing is sent until the player sends it.

## Telegram integration security

- The signature of Telegram's launch data is verified on the server with the bot's secret key, which never leaves the server.
- Unsigned launch information supplied by the app is never used to identify the player.
- Invalid launch data is refused with "Couldn't sign you in"; expired launch data requires reopening the Mini App.

## Data access restrictions

- Every player request must carry a valid access token. The account is always the one in the token.
- **Scores, multipliers, unlocks and player levels are calculated by the server only.** The app cannot set them, and no endpoint allows the app or an AI system to write them.
- Saved game results cannot be modified or deleted through the game; they are protected in the database against changes.
- The internal interface for automation and AI tools returns only verified geographic facts and accepts only question drafts for human review. It does not provide access to player data, and it is disabled unless it has been configured with its own secret key.

## AI and content

- AI may help write **draft questions** from verified facts. A person reviews and approves every draft before players can see it.
- AI is **never** used to check answers or calculate points.

## Privacy principles

1. **Collect what the game needs.** The game stores Telegram profile information, game results and answers; it asks for nothing else.
2. **The player's data stays private.** No public profiles or rankings.
3. **The server is the referee.** Identity, scores and unlocks are decided only by the server.
4. **Never publish secrets.** Keys, passwords and server details are never part of the app, the documentation or the public source files.
5. **Preserve player progress.** Profiles and saved results are never reset or rewritten.

## Not available in version 2.3.0

- Deleting or exporting a profile from within the app.
- A published privacy policy or terms of service.

# What's New in This Version

**Version:** 2.3.0
**Release date:** 2026-11-18

**Initial documentation release.** Version 2.3.0 is the first version with public documentation. The other sections of this version document the complete game as implemented at version 2.3.0; they are the baseline for all later versions. The changes below are the changes made in the 2.3.0 release itself. Earlier releases are summarized in the [changelog](../../changelog/index.md).

## New Features

- **Pinch-to-zoom in Level 1** on touch screens (iOS and Android). Two fingers zoom around the point between them, and moving two fingers moves the map.
- One finger still only taps, so answering works exactly as before. A pinch never counts as an answer.
- Every new round starts from its own zoomed view of the right area.

## Improvements

- **All levels:** when pinching, the point under the fingers now stays in place, and a two-finger drag moves the map. Before, zoom was centred only on the point where the pinch started.
- **All levels:** the map can no longer be pushed out of sight. Its centre always stays on the map, and zooming out is limited.
- **All levels:** smoother map movement (the map is redrawn at most once per screen frame).
- **iOS:** the page itself no longer zooms while the map's gestures are active.

## Bug Fixes

- No bug fixes in this release.

## Technical Updates

- The change affects only the app. There is no change to scoring, levels, unlocking, the server or stored data.
- Desktop behaviour in Level 1 is unchanged: a mouse click answers, and the mouse wheel and mouse drag do not zoom or move the map.
- Public documentation (this website) and a machine-readable documentation index for AI systems were introduced with this version.

## Breaking Changes

- None.

## Known Issues

- In Level 1, a zoomed map cannot be moved with one finger, because one finger is reserved for tapping. Use two fingers to move the map.
