Self-hosted engine for real-world, geolocated games and interactive routes.
SAGA Engine lets you create missions where players move through real places, open map nodes, scan QR/NFC props, collect items, solve challenges and progress through a route managed from Mission Control.
Current public release: v0.0.1.
| Game idea | Example |
|---|---|
| Treasure hunt | Follow a route and collect QR objects. |
| Urban escape | Unlock clues across real locations. |
| Family gymkhana | Outdoor challenges with map nodes. |
| Orientation route | GPS, compass and clue navigation. |
| Education/tourism trail | Guided interactive stops. |
| Team field mission | Move, scan, collect and sync progress. |
Admin creates mission
↓
Adds route nodes
↓
Chooses game preset
↓
Generates QR / physical props
↓
Players open the player app
↓
Move / scan / solve / collect
↓
Progress is saved
↓
Admin monitors and adjusts players
| Concept | Meaning |
|---|---|
| Mission | The whole game route or experience. |
| Node | A step on the route, usually linked to a map position. |
| Game family | Reusable runtime, such as GPS signal hunt or compass bearing. |
| Preset | A configured game option shown in the editor. |
| Requirement | Something needed before a node can be completed. |
| Inventory item | QR/NFC/object collected by the player. |
| Progress | Player state, current node, finished status and offline queue. |
Current player foundations:
- map-first route view;
- GPS/radius based nodes;
- QR inventory collection;
- player/team identity markers;
- local/offline-first foundations;
- mission pack/preload foundation;
- field photo pins;
- route progress flow.
Player loop:
Move -> Find -> Scan -> Collect -> Solve -> Continue
Mission Control is the main authoring and control interface.
| Area | Current capability |
|---|---|
| Mission editing | Map-first route editing and node ordering. |
| Game authoring | Game catalog with runtime/offline status. |
| QR props | QR card builder for objects, keys, clues and bonus cards. |
| Players | Profile management and progress controls. |
| Live control | Reset, move back, move forward or finish a player run. |
| Families | Overview of gameplay families. |
The old classic admin has been retired. /admin redirects to /admin-react.
signal_hunt
bearing_hunt
circuit_matrix
Authoring direction:
Family -> Preset/Game -> Completion method -> Requirement -> Reward
SAGA is designed for field conditions where mobile coverage may be unreliable.
Current foundations:
- local player progress;
- QR inventory cards;
- physical event queue foundations;
- mission pack/preload foundations;
- sync-oriented backend events;
- runtime data separated from repository code.
Runtime state is kept outside the public repository.
JSON remains supported for simple/self-hosted setups. SQLite can be enabled for production-style runtime storage:
SAGA_STORAGE_BACKEND=sqlite
SAGA_SQLITE_DB=/absolute/path/to/saga.sqlite3Production should run from a locally built Docker image with runtime data mounted separately.
Useful docs:
docs/operations/clean-docker-production-deploy.mddocs/operations/sqlite-runtime-only.mddocs/operations/docker-runtime.md
Do not commit:
- real
.envfiles; - secrets or tokens;
- private keys;
- logs;
- backups;
- local databases;
- runtime player state;
- private operational paths or IPs;
- live player data.
Run guards:
python scripts/check_audit_guards.py --base origin/mainpython scripts/check_audit_guards.py --base origin/main
cd frontend && npm run build
ADMIN_PASS='pytest_admin_password' PYTHONPATH=. ./.venv/bin/python -m pytest -qThis repository was reset at v0.0.1 as the first public baseline.
main intentionally starts from one public release commit. Earlier private/internal iteration history is not part of the public baseline.
Near-term:
- improve visual game authoring in Mission Control;
- simplify the admin node editor;
- make game presets easier to understand and edit;
- add more reusable offline-ready game presets;
- harden QR route completion with explicit, predictable flow;
- improve PWA/offline polish;
- continue backend modularization.
MIT.