Un motor de misiones de campo geolocalizado, en tiempo real y offline-first.
Diseñado para experiencias de juego presencial con equipos, QR físicos, GPS y minijuegos.
SAGA Engine es una plataforma completa para diseñar y ejecutar misiones de campo gamificadas en el mundo real. Los jugadores reciben una ruta de nodos GPS, escanean QRs físicos, completan minijuegos y acumulan logros — todo ello funciona tanto con conexión como sin ella.
Pensado para escape rooms urbanos, gymkhanas, formaciones corporativas, tours guiados y cualquier experiencia donde quieras convertir el espacio real en un tablero de juego.
- Mapa interactivo basado en Leaflet + OpenStreetMap con nodos de misión geolocalizados
- Indicador de posición GPS del jugador con seguimiento dinámico
- Cálculo de distancia al nodo activo y radio de activación configurable
- Vista de ruta completa y modo "overview" de toda la misión
- Marcadores de equipo en tiempo real sobre el mapa
- Soporte completo de GPS del navegador con retroalimentación de precisión
- Modo debug de geolocalización para pruebas desde escritorio (permite mover manualmente la posición)
- Petición de GPS en el Login con flujo de permiso claro
- Entrada sin GPS permitida, con solicitud de posición simulada en debug
- Service Worker PWA con caché de assets y shell del jugador
- Mission Pack: descarga completa de la misión para jugar sin conexión
- Caché de teselas de mapa (tiles) con precarga configurable antes de salir al campo
- Sincronización automática de progreso offline cuando vuelve la conexión
- Pruebas de campo (fotos) almacenadas localmente y sincronizadas después
Sistema extensible de familias de minijuegos. En v2.1.0 incluye:
| Family | Descripción |
|---|---|
| Matriz de Circuitos | Conecta circuitos en una cuadrícula para encender nodos |
| Código Secuencial | Descifra y replica una secuencia de colores / símbolos |
| Mosaico de Lugar | Reconstruye una imagen fragmentada del lugar |
| Laberinto de Equilibrio | Laberinto controlado por el acelerómetro |
| Desafío de Audio (Audio Challenge) | Escucha, identifica patrones o resuelve acertijos sonoros |
Cada familia tiene editor visual en el panel de administración y runtime propio en el cliente.
- Inventario con objetos recolectables (coleccionables, pistas, ítems de misión)
- Previsualización del siguiente nodo y su juego asociado
- Descripción contextual de cómo se juega cada minijuego
- Guía de herramientas integrada (asistente de campo)
- Descarga de fotos de campo como ZIP
- Perfiles de jugador y equipos configurables desde el admin
- Presencia de equipo en tiempo real (posiciones en el mapa)
- Soporte para modos solo y equipo
- Generación de tarjetas QR físicas desde el admin (QR Studio)
- Validación de QR con lógica de distancia — aviso centrado en pantalla si el jugador está demasiado lejos
- Soporte para tipos de nodo físico: Objeto QR, Llave QR, Pista QR, Bonus Oculto
- Panel de preview de requisitos antes de activar un nodo
- Captura de fotos geolocalizadas desde el cliente jugador
- Visor de fotos sobre el mapa con superposición de posición
- Eliminación de fotos propias
- Descarga en ZIP desde el panel de herramientas del jugador y desde el admin
- Constructor de misiones con nodos, etapas y rutas
- Editor visual de minijuegos por familia
- Gestión de jugadores y perfiles de equipo
- Mapa de misión en admin con vista de posiciones en vivo
- QR Studio para generar y gestionar tarjetas QR imprimibles
- Configuración de la misión, idioma y parámetros globales
- Offline Vault: resumen del estado de preparación offline de cada jugador
saga_engine/
├── main.py # FastAPI app principal
├── requirements.txt # Dependencias Python
├── Dockerfile # Imagen Docker (Python 3.13-slim)
├── frontend/ # App React (Vite + TypeScript)
│ ├── src/
│ │ ├── App.tsx # Router raíz (Login / Player / Admin)
│ │ ├── login/ # LoginApp — selección de jugador + GPS
│ │ ├── player/ # PlayerApp — mapa, HUD, mochila, minijuegos
│ │ │ ├── components/ # PlayerHud, PlayerShell, MapSurface…
│ │ │ ├── minigames/ # Core + familias de minijuegos
│ │ │ ├── offline/ # PWA, Mission Pack, GPS cache…
│ │ │ └── utils/ # GPS, geo, stagePosition…
│ │ ├── admin/ # AdminApp — panel de administración
│ │ └── shared/ # API, tipos, identidad, offline vault…
│ └── public/ # Assets estáticos, manifest PWA, SW
├── scripts/ # Scripts de despliegue y auditoría
└── tests/ # Tests de backend (pytest)
Stack:
- Backend: Python 3.13 + FastAPI + SQLite (vía adaptadores)
- Frontend: React 19 + TypeScript + Vite + Leaflet
- Deploy: Docker (imagen única), desplegable en Raspberry Pi 4 o cualquier servidor Linux
- PWA: Service Worker con estrategia offline-first
- Docker
- (Opcional) Node.js 20+ para desarrollo frontend local
# Clonar
git clone https://github.com/tu-usuario/saga_engine.git
cd saga_engine
# Configurar entorno
cp prod.env.example prod.env
# Editar prod.env con tus valores
# Construir y arrancar
docker build -t saga_engine:latest .
docker run -d \
--name saga_engine_app \
-p 8096:5000 \
--env-file prod.env \
-v $(pwd)/data:/app/data \
saga_engine:latestEl script deploy_saga_safe.sh levanta primero un candidato en puerto alternativo, hace smoke test, y solo promueve si todo va bien:
bash scripts/deploy_saga_safe.sh saga_engine:latest --build --promotecd frontend
npm install
npm run dev
# → http://localhost:5173| Variable | Descripción | Ejemplo |
|---|---|---|
SECRET_KEY |
Clave secreta para sesiones admin | cambiar-en-produccion |
ADMIN_PASSWORD |
Contraseña del panel de admin | mi-password |
SAGA_VERSION |
Versión mostrada en el cliente | 2.1.0 |
SAGA_BUILD_TIME |
Timestamp de compilación | 2026-07-07T14:00:00+0200 |
DATA_DIR |
Directorio de datos persistentes | /app/data |
La misión se configura desde el panel de administración (/admin-react):
- Settings → Nombre de la misión, historia, idioma, jugadores
- Mission Builder → Crear nodos con coordenadas GPS y radio de activación
- Node Editor → Asignar familia de minijuego y configurar sus parámetros
- Physical QR → Generar y descargar tarjetas QR imprimibles
- Players → Gestionar perfiles de jugador y equipos
- Offline Prep → Verificar que todos los jugadores tienen la misión descargada
En entornos sin GPS real (escritorio, pruebas):
- Entra al jugador desde
/player/TU-JUGADOR - En la barra inferior → botón de debug 🐛
- Pulsa en el mapa para simular tu posición
Para pruebas de distancia a nodos, usa el modo debug para colocarte dentro del radio del nodo activo.
El sistema está optimizado para correr en una Raspberry Pi 4 (arm64):
# En la Pi
git clone https://github.com/tu-usuario/saga_engine.git
cd saga_engine
# Primera vez
docker build -t saga_engine:latest .
bash scripts/deploy_saga_safe.sh saga_engine:latest --promote
# Actualizaciones
# (desde el PC de desarrollo, subir los cambios a la Pi y re-ejecutar)
bash scripts/deploy_saga_safe.sh saga_engine:latest --build --promoteEl script gestiona automáticamente:
- Construcción de imagen nueva
- Prueba en puerto alternativo (18096)
- Smoke test de las rutas principales
- Promoción a producción (8096) solo si todo va bien
- Limpieza del candidato
# Instalar dependencias de test
pip install -r requirements-dev.txt
# Ejecutar todos los tests
pytest tests/ -v
# Tests específicos
pytest tests/test_game_state_repository.py -v
pytest tests/test_offline_progression_sync_api.py -vVer CHANGELOG.md para el historial completo de versiones.
MIT — ver LICENSE
Construido con ❤️ para misiones de campo reales.
SAGA Engine v2.1.0 — 2026