🎮 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.
⚠️ Proyecto en desarrollo - Actualmente en fase Alpha (v0.0.5-alpha)
🎓 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
🎮 Cómo Jugar
Preparación
- Únete a una sala - Exactamente 3 jugadores requeridos
- Rol asignado - Recibes un rol de productor único al azar
- Tokens iniciales - Comienzas con 5 tokens de tu tipo
Mecánicas de Juego
- Haz ofertas - Click en otros jugadores para ofertar
- Responde ofertas - Acepta, rechaza o haz "snatch"
- Acumula puntos - Tokens propios = 1pt, ajenos = 2pts
- 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 (próximamente)
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 (opcional)
cd admin
npm run dev
URLs de desarrollo
- Cliente: http://localhost:3000
- Servidor: http://localhost:2567
- Admin: http://localhost:3001 (próximamente)
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
⚙️ 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) │
│ Port 3000 │ │ Port 2567 │ │ Port 3001 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Docker + │
│ Nginx Proxy │
└─────────────────┘
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 (próximamente)
├── 🎮 gameRules.md # Reglas del juego detalladas
├── 🐳 docker-compose.yml # Orquestación Docker
├── 📋 CLAUDE.md # Guía de desarrollo
└── 📖 README.md # Este archivo
🤝 Contribuir
- Fork el proyecto
- Crea una feature branch (
git checkout -b feature/AmazingFeature) - Commit tus cambios (
git commit -m 'Add AmazingFeature') - Push a la branch (
git push origin feature/AmazingFeature) - 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
- Ve a Configuración en la UI
- Habilita "Logs de depuración"
- 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
- 🐳 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