367 lines
11 KiB
Markdown
367 lines
11 KiB
Markdown
# 🎮 SnatchGame
|
|
|
|
[](https://github.com/username/snatchgame)
|
|
[](LICENSE)
|
|
[](https://nodejs.org/)
|
|
[](https://vuejs.org/)
|
|
[](https://colyseus.io/)
|
|
|
|
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
|
|
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](https://colyseus.io/)** - Framework multijugador en tiempo real
|
|
- **Node.js** + **TypeScript**
|
|
- **Express.js**
|
|
|
|
### Frontend
|
|
- **[Vue 3](https://vuejs.org/)** - 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
|
|
```bash
|
|
git clone https://github.com/username/snatchgame.git
|
|
cd snatchgame
|
|
```
|
|
|
|
### 2. Instalar dependencias
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
# Presiona Ctrl+Shift+P → "Tasks: Run Task"
|
|
# Selecciona "Start All Services"
|
|
```
|
|
|
|
#### Opción 2: Manual
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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`):
|
|
```env
|
|
VITE_SERVER_URL=ws://localhost:2567
|
|
NODE_ENV=development
|
|
PORT=2567
|
|
```
|
|
|
|
**Producción** (`.env.production`):
|
|
```env
|
|
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
|
|
```bash
|
|
# Los tipos se generan automáticamente del servidor al cliente
|
|
npm run generate-types
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# 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
|
|
|
|
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
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
# Build y start
|
|
docker-compose up -d
|
|
|
|
# Logs
|
|
docker-compose logs -f
|
|
|
|
# Stop
|
|
docker-compose down
|
|
```
|
|
|
|
### Manual
|
|
```bash
|
|
# Build servidor
|
|
cd server && npm run build
|
|
|
|
# Build cliente
|
|
cd client && npm run build
|
|
|
|
# Start producción
|
|
npm run start
|
|
```
|
|
|
|
## 📋 Roadmap
|
|
|
|
### Funcionalidades del Juego
|
|
- [x] 🎮 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
|
|
- [x] 📱 Layout responsivo optimizado
|
|
- [x] 🎯 Formulario con botones +/-
|
|
- [x] 🔄 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](LICENSE) para más detalles.
|
|
|
|
## 👥 Autores
|
|
|
|
- **NucleoServices** - *Desarrollo inicial* - [@draganel](https://github.com/draganel)
|
|
|
|
## 📞 Soporte
|
|
|
|
¿Encontraste un bug? ¿Tienes una sugerencia?
|
|
|
|
- 🐛 **Issues**: [GitHub Issues](https://github.com/username/snatchgame/issues)
|
|
- 💬 **Discusiones**: [GitHub Discussions](https://github.com/username/snatchgame/discussions)
|
|
- 📧 **Email**: support@nucleoservices.com
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**⭐ ¡Dale una estrella si te gusta el proyecto! ⭐**
|
|
|
|
Hecho con ❤️ por **NucleoServices**
|
|
|
|
</div> |