🎮 SnatchGame

Un juego multijugador educativo que simula la evolución de instituciones y cooperación, basado en el "Snatch Game" de Elinor Ostrom. Construido con Colyseus.io y Vue 3 para redes locales.

✨ Admin Dashboard Completo - Versión Alpha (v0.0.8-alpha) con interfaz de administración profesional

🎓 Sobre el Juego

Snatch or Share es una simulación interactiva que permite a los participantes experimentar cómo las reglas, la confianza y los arreglos institucionales afectan la cooperación en intercambios descentralizados. Basado en el trabajo de la Nobel de Economía Elinor Ostrom sobre gobernanza de recursos comunes.

🎯 Objetivos Educativos

• Demostrar la evolución de instituciones en el intercambio
• Experimentar con diferentes sistemas de gobernanza
• Entender el rol de la confianza en la cooperación
• Aplicar conceptos de teoría de juegos en tiempo real

🚀 Características del Juego

• 👥 Multijugador exacto - Salas de exactamente 3 jugadores
• 🎭 Roles únicos - Productor de Pavos, Café o Maíz
• ⚡ Tiempo real - Sincronización instantánea con Colyseus.io
• 🔄 Sistema de intercambio - Ofertas, negociaciones y "snatch"
• 📊 Cálculo automático - Puntuación basada en tokens
• 📱 Responsive - Interfaz optimizada para desktop y móvil
• 🎯 Red local - Funciona completamente offline
• 📈 Progresión por rondas - 5 rondas con reglas evolutivas
• 🎛️ Admin Dashboard - Interfaz completa de administración y monitoreo
• 🔔 Notificaciones - Sistema completo de alertas para jugadores

🎮 Cómo Jugar

Preparación

1. Únete a una sala - Exactamente 3 jugadores requeridos
2. Rol asignado - Recibes un rol de productor único al azar
3. Tokens iniciales - Comienzas con 5 tokens de tu tipo

Mecánicas de Juego

1. Haz ofertas - Click en otros jugadores para ofertar
2. Responde ofertas - Acepta, rechaza o haz "snatch"
3. Acumula puntos - Tokens propios = 1pt, ajenos = 2pts
4. Estrategia - Coopera o compite según las reglas de la ronda

Progresión (5 Rondas)

• Ronda 1-2: Estado de naturaleza (sin reglas)
• Ronda 3: Reglas contraproductivas
• Ronda 4: Normas sociales (shame tokens)
• Ronda 5: Gobernanza institucional (juez rotativo)

🛠️ Stack Tecnológico

Backend

• Colyseus.io - Framework multijugador en tiempo real
• Node.js + TypeScript
• Express.js

Frontend

• Vue 3 - Composition API
• TypeScript - Tipado estricto
• Vite - Build tool ultra-rápido
• CSS vanilla - Estilos custom

Desarrollo

• Schema-codegen - Sincronización automática de tipos
• Hot reload - Desarrollo en vivo
• ESLint + Prettier - Calidad de código

📦 Instalación

Prerrequisitos

• Node.js >= 18.0.0
• npm >= 8.0.0

1. Clonar el repositorio

git clone https://github.com/username/snatchgame.git
cd snatchgame

2. Instalar dependencias

# Instalar todas las dependencias automáticamente
npm run install:all

# O manualmente:
# Servidor
cd server && npm install

# Cliente  
cd ../client && npm install

# Admin
cd ../admin && npm install

🚀 Ejecución

Desarrollo

Opción 1: VSCode Tasks (Recomendado)

# Presiona Ctrl+Shift+P → "Tasks: Run Task"
# Selecciona "Start All Services"

Opción 2: Manual

# Terminal 1 - Servidor
cd server
npm run dev

# Terminal 2 - Cliente
cd client
npm run dev

# Terminal 3 - Admin Dashboard
cd admin
npm run dev

URLs de desarrollo

• Cliente: http://localhost:3000
• Servidor: http://localhost:2567
• Admin Dashboard: http://localhost:3001
• Monitor Colyseus: http://localhost:2567/monitor

Producción

# Build
npm run build

# Deploy con Docker
docker-compose up -d

🎮 Interfaz del Juego

Vista Desktop

• Layout de 2 columnas: Jugadores a la izquierda, ofertas a la derecha
• Jugador actual prominente: Tarjeta grande en la parte inferior
• Otros jugadores compactos: Tarjetas pequeñas y clickeables
• Panel de ofertas: Scroll customizado con ofertas en tiempo real

Vista Móvil

• Layout vertical: Jugadores arriba, ofertas abajo
• Formulario modal: Ofertas en modal flotante
• Botones optimizados: +/- táctiles para cantidades
• Scroll adaptativo: Altura limitada con navegación suave

Componentes Principales

• PlayerCard: Información de jugador con tokens y puntos
• TradeOfferCard: Ofertas con acciones (Accept/Reject/Snatch)
• MakeOfferForm: Formulario con botones +/- intuitivos
• OfferModal: Modal flotante para crear ofertas dirigidas

🎛️ Admin Dashboard

El Admin Dashboard proporciona control completo y monitoreo en tiempo real del juego, diseñado tanto para administradores técnicos como para comentaristas no-técnicos.

📊 Características Principales

Información en Tiempo Real

• 👥 Lista de Jugadores Detallada: Nombre, sala, rol, tipo de productor y tokens actuales
• 📈 Estadísticas Globales: Jugadores conectados, partidas activas, ronda actual
• 🎯 Estado del Juego: En progreso, pausado, esperando jugadores
• 🔄 Actualización Automática: SSE con polling cada 500ms

Control de Jugadores

• 🚫 Expulsar Jugador Individual: Con notificación al cliente y redirección automática
• 🚫🚫 Expulsar Todos los Jugadores: Vaciar todas las salas con notificaciones apropiadas
• 👤 Información Detallada: Ver tokens específicos (🦃 pavos, ☕ café, 🌽 maíz)

Control del Juego

• ⏸️ Pausar Juego: Pausar todas las partidas activas
• ▶️ Reanudar Juego: Reanudar partidas pausadas
• ⏮️ Retroceder Ronda: Cambio global a ronda anterior (mínimo 1)
• ⏭️ Avanzar Ronda: Cambio global a ronda siguiente (máximo 10)

Notificaciones a Clientes

• 🔔 Expulsión: Mensaje personalizado y redirección automática
• 🎯 Cambio de Ronda: Notificación inmediata de nuevas rondas
• ⏸️ Estado del Juego: Alertas de pausa/reanudación

🎯 Usuarios Objetivo

• 👨‍💼 Administrador No-Técnico: Vista limpia con estadísticas esenciales
• 👨‍💻 IT Profesional: Información de debugging y estado técnico detallado
• 🎙️ Comentaristas Deportivos: Información clara para narración en vivo

🏗️ Arquitectura Técnica

• API Oficial Colyseus: Uso de matchMaker.query() y matchMaker.remoteRoomCall()
• Comunicación Bidireccional: SSE para updates, HTTP para control
• Sin Variables Globales: Implementación limpia y mantenible
• Type Safety: Sincronización completa de tipos TypeScript

⚙️ Configuración

Variables de Entorno

Desarrollo (.env.development):

VITE_SERVER_URL=ws://localhost:2567
NODE_ENV=development
PORT=2567

Producción (.env.production):

VITE_SERVER_URL=wss://your-domain.com
NODE_ENV=production
PORT=2567

Configuración de Logs

• Desarrollo: Logs habilitados por defecto
• Producción: Logs deshabilitados por defecto
• Usuario: Configurable en "Configuración" → "Logs de depuración"

🏗️ Arquitectura

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client UI     │    │  Colyseus       │    │   Admin UI      │
│   (Vue 3)       │◄──►│   Server        │◄──►│   (Vue 3 + SSE) │
│   Port 3000     │    │   Port 2567     │    │   Port 3001     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Docker +       │
                    │  Nginx Proxy    │
                    └─────────────────┘

Comunicación Admin

• SSE (Server-Sent Events): Servidor → Admin UI
• Polling: Actualización cada 500ms
• Control: Admin → Servidor (HTTP endpoints)

Sincronización de Tipos

# Los tipos se generan automáticamente del servidor al cliente
npm run generate-types

🧪 Testing

# Servidor
cd server
npm test

# Cliente
cd client
npm test

# E2E
npm run test:e2e

📁 Estructura del Proyecto

snatchgame/
├── 📁 server/              # Colyseus.io backend
│   ├── src/
│   │   ├── rooms/
│   │   │   └── GameRoom.ts # Lógica principal del juego
│   │   ├── app.config.ts   # Configuración Colyseus
│   │   └── index.ts        # Entry point
│   └── README.md           # Documentación del servidor
├── 📁 client/              # Vue 3 frontend  
│   ├── src/
│   │   ├── components/     # Componentes Vue
│   │   │   ├── Game.vue    # Componente principal
│   │   │   ├── PlayerCard.vue
│   │   │   ├── TradeOfferCard.vue
│   │   │   ├── MakeOfferForm.vue
│   │   │   ├── ScrollableOffers.vue
│   │   │   └── OfferModal.vue
│   │   ├── services/       # Game client & logger
│   │   │   ├── gameClient.ts
│   │   │   └── logger.ts
│   │   ├── types/          # Auto-generated types
│   │   │   ├── GameState.ts
│   │   │   ├── Player.ts
│   │   │   ├── TradeOffer.ts
│   │   │   └── TokenInventory.ts
│   │   └── main.ts
│   ├── server.js           # Express server (producción)
│   └── README.md           # Documentación del cliente
├── 📁 admin/               # Admin dashboard
│   ├── src/
│   │   ├── components/     # Componentes Vue admin
│   │   ├── services/       # Admin service
│   │   │   └── adminService.ts
│   │   └── main.ts
│   ├── server.js           # Express server (producción)
│   └── README.md           # Documentación del admin
├── 🎮 gameRules.md         # Reglas del juego detalladas
├── 🐳 docker-compose.yml   # Orquestación Docker
├── 📋 CLAUDE.md            # Guía de desarrollo
└── 📖 README.md            # Este archivo

🤝 Contribuir

1. Fork el proyecto
2. Crea una feature branch (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add AmazingFeature')
4. Push a la branch (git push origin feature/AmazingFeature)
5. Abre un Pull Request

Guías de contribución

• Sigue las convenciones de código existentes
• Añade tests para nuevas características
• Actualiza la documentación si es necesario
• Los commits deben ser descriptivos

🐛 Debugging

Logs de desarrollo

1. Ve a Configuración en la UI
2. Habilita "Logs de depuración"
3. Abre DevTools (F12) para ver logs detallados

Comandos útiles

# Verificar puertos libres
lsof -i :2567,3000,3001

# Cerrar procesos
pkill -f "ts-node-dev" && pkill -f "vite"

# Regenerar tipos
cd client && npm run generate-types

🚀 Deploy

Docker (Recomendado)

# Build y start
docker-compose up -d

# Logs
docker-compose logs -f

# Stop
docker-compose down

Manual

# Build servidor
cd server && npm run build

# Build cliente
cd client && npm run build

# Start producción
npm run start

📋 Roadmap

Funcionalidades del Juego

• 🎮 Ronda 1: Estado de naturaleza (completado)
• 🎭 Ronda 2-5: Implementar reglas evolutivas
• 👨‍⚖️ Sistema de Judge rotativo
• 😔 Shame tokens y penalizaciones
• 📊 Estadísticas por ronda
• 🏆 Sistema de puntuación final

Mejoras de UI/UX

• 📱 Layout responsivo optimizado
• 🎯 Formulario con botones +/-
• 🔄 Scroll customizado para ofertas
• 🎨 Themes y customización visual
• 🔊 Efectos de sonido y feedback
• ⚡ Animaciones de transición
• 📊 Gráficos y visualizaciones

Infraestructura

• 📈 UI de administración completa
  • Dashboard con estadísticas en tiempo real
  • Panel de control para administrar partidas
  • Sistema de expulsión de jugadores
  • Pausa/reanudación de partidas
  • Control de rondas globales
  • Información detallada de jugadores con tokens
  • Notificaciones automáticas a clientes
  • Historial de partidas anteriores
• 🐳 Docker en producción
• 📱 PWA support
• 🌍 Multi-idioma (EN/ES)
• 🔒 Sistema de salas privadas
• 📄 Exportar resultados (PDF/CSV)

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo LICENSE para más detalles.

👥 Autores

• NucleoServices - Desarrollo inicial - @draganel

📞 Soporte

¿Encontraste un bug? ¿Tienes una sugerencia?

• 🐛 Issues: GitHub Issues
• 💬 Discusiones: GitHub Discussions
• 📧 Email: support@nucleoservices.com

---

⭐ ¡Dale una estrella si te gusta el proyecto! ⭐

Hecho con ❤️ por NucleoServices