02GeoQuest
Playable Map Studio — turn any QGIS vector layer into an educational quiz game • v1.0.3
1. Overview
02GeoQuest transforms QGIS vector layers into interactive geography games, educational quizzes, data-familiarisation tools, and public-engagement challenges. It features 8 game modes, 3 difficulty levels, 3 joker types, a persistent leaderboard, a full class-mode with student profiles and CSV export, and a self-contained offline HTML game exporter. The entire system operates locally inside QGIS with zero external dependencies, no API keys, no accounts, and no pip-installed packages.
The plugin is a dock-based quiz studio with four pages: Play (the active game), Builder (configuration), Scores (leaderboard), and Share (HTML export and class mode).
2. Game Modes
| Mode | Description | Requires | HTML Export |
|---|---|---|---|
| Map Hunt ("locate") | Click the named feature on the QGIS canvas | Any features | — |
| Value Duel ("bigger") | Two features: pick the one with the larger numeric value | Numeric field | Yes |
| Distance Guess ("distance") | Estimate the ground distance between two places | Geographic centroids | Yes |
| Know the Shape ("silhouette") | Identify a polygon feature from its simplified outline | 4+ polygons | Yes |
| Attribute Guess ("attr_guess") | Estimate a numeric attribute via a slider | 2+ numeric values | Yes |
| Ranking ("ordering") | Order 3–4 features from highest to lowest value | 3+ distinct values | Yes |
| Nearest Neighbour ("nearest") | Identify which feature is closest to a reference | 4+ valid records | Yes |
| Blind Zoom ("blind_zoom") | Canvas zooms to a feature; name it | 2+ records | — |
Map Hunt and Blind Zoom are excluded from HTML export because they require QGIS canvas interaction.
3. Difficulty Levels
| Level | Timer | Choices | Tolerance |
|---|---|---|---|
| Easy | 60 s | 3 | 0.40 |
| Medium | 30 s | 4 | 0.25 |
| Hard | 15 s | 6 | 0.10 |
Tolerance governs the acceptable error ratio for distance guesses and attribute slider estimates. A tolerance of 0.25 means the estimate must be within ±25% of the true value.
4. Jokers
Three Joker Types, Each Usable Once Per Quest
- Eliminate: Removes 2 wrong multiple-choice options. Available in: Value Duel, Silhouette, Nearest Neighbour, Blind Zoom.
- Value Hint: Narrows a slider or spinbox range by 50% around its midpoint. Available in: Attribute Guess, Distance Guess.
- Map Hint: Zooms the canvas to a wider hint area (2.5× the feature's bounding box). Available in: Map Hunt.
Default joker pool: 3 total (configurable 0–9).
5. Scoring Engine
Points are computed per answer as:
- Base: 500 points
- Speed bonus: max(0, 150 − elapsed_seconds × 8)
- Streak bonus: min(300, max(0, streak − 1) × 30)
- Closeness multiplier: clamped to [0.25, 1.0]; rewards near-misses for slider/distance modes
- Total: int((500 + speed_bonus + streak_bonus) × closeness)
Timed-out answers are automatically wrong regardless of correctness. The game ends when rounds are exhausted or lives reach zero. The session summary includes: total score, rounds played, correct count, accuracy percentage, best streak, lives remaining, and total duration.
6. Builder Controls
| Section | Control | Options |
|---|---|---|
| Source Layer | Layer picker, label field, numeric field | Single vector layer (layer A) |
| Second Layer | Checkbox toggle, duplicate controls | Optional cross-layer play (layer B) |
| Challenge Mix | 8 checkboxes | Modes auto-filtered by data availability |
| Difficulty | Three toggle buttons (Easy / Medium / Hard) | Affects timer, choices, tolerance |
| Quest Rules | Title combo with presets, rounds (3–60), lives (1–10), jokers (0–9) | Preset titles: My Map Quest, City Explorer, Data Detective, etc. |
7. Workflow Guide
- Open the 02GeoQuest dock from the toolbar.
- On the Builder tab, select a vector layer. Optionally add a second layer for cross-layer play.
- Choose a label field (for display names) and an optional numeric field (for value-based modes).
- Select game modes from the 8 checkboxes. Modes lacking sufficient data are auto-greyed.
- Set difficulty and quest rules (rounds, lives, jokers).
- Click Start the quest. The dock switches to the Play page.
- Questions appear in sequence with the appropriate input widget (multiple-choice buttons, slider, spinbox, or map pick).
- The timer bar changes colour at 50% (yellow) and 25% (red). Use jokers as needed.
- After the last round or when lives reach zero, the final score is saved to the leaderboard.
8. Class Mode and Student Profiles
Teacher Tools
Student profiles: Create named profiles with emoji avatars (10 choices: map, cityscape, globe, compass, pin, mountain, wave, leaf, star, fire). Profiles are stored as JSON in QgsSettings.
Session tracking: Select an active profile before playing; each completed quest is logged with player name, avatar, quest title, difficulty, score, accuracy, best streak, correct count, rounds, duration, and date. Sessions persist across QGIS restarts (last 300 sessions retained).
CSV export: Export all sessions to a UTF-8 BOM CSV file for grading and record-keeping via standard csv.DictWriter.
9. Offline HTML Game Export
Self-Contained, Zero-Dependency HTML
Exports a single HTML file with an embedded JavaScript game engine that fully reimplements the question generation and scoring logic. Excludes Map Hunt and Blind Zoom modes. Features: dark mode with CSS custom properties and localStorage persistence, responsive single-column layout below 560 px, score animation with CSS keyframes, progress dots (violet=pending, green=correct, red=wrong), ranking via Up/Down buttons, results screen with replay, and XSS-safe JSON embedding (angle brackets escaped to Unicode sequences). Zero CDN, zero network calls, zero tracking.
10. Technical Notes
- Pure-Python core: The game engine, question factory, scoring, and profile manager have zero QGIS imports and are independently testable with plain CPython.
- LCG-based PRNG: A Knuth MMIX linear congruential generator (state 32-bit, seed from
time.time_ns()) avoids stdlibrandomto keep QGIS Hub Bandit B311 scans clean. - Layer data serialisation: Features are immediately serialised to plain dictionaries with no QGIS object references held, keeping memory predictable and enabling pure-Python tests.
- Question factory: Maintains an 8-deep short-term memory of recent feature combinations to avoid repeats; pre-computes all valid pairs, distance pairs, and nearest-neighbour options on construction.
- Adaptive theme: All UI colours derive from the active Qt
QPalettewith WCAG 4.5:1 contrast compliance. Reapplies onPaletteChangeandApplicationPaletteChangeevents. - QGIS compatibility: 3.34 through 4.x. Dual Qt5/Qt6 support via try/except for
QActionimport location.
11. Literature
- Prensky, M. (2001). Digital Game-Based Learning. McGraw-Hill.
- Gee, J. P. (2003). What video games have to teach us about learning and literacy. Computers in Entertainment, 1(1), 20. DOI: 10.1145/950566.950595
- Hamari, J., Koivisto, J., & Sarsa, H. (2014). Does gamification work? — A literature review of empirical studies on gamification. Proceedings of the 47th Hawaii International Conference on System Sciences, 3025–3034. DOI: 10.1109/HICSS.2014.377
- Kapp, K. M. (2012). The Gamification of Learning and Instruction: Game-Based Methods and Strategies for Training and Education. Pfeiffer.