feat(economy): add game system guide and ensure user existence in database for partnership stats

2025-10-05 05:08:59 -05:00
parent 8afd897087
commit 68f629d637
2 changed files with 663 additions and 0 deletions
--- a/GAME_SYSTEM_GUIDE.md
+++ b/GAME_SYSTEM_GUIDE.md
@@ -0,0 +1,654 @@
+# 📖 Guía del Sistema de Juegos - Amayo Bot
+
+## Índice
+- [Introducción](#introducción)
+- [Estructura del Sistema](#estructura-del-sistema)
+- [Creación de Items](#creación-de-items)
+- [Sistema de Tienda](#sistema-de-tienda)
+- [Áreas de Juego](#áreas-de-juego)
+- [Mobs (Enemigos)](#mobs-enemigos)
+- [Sistema de Crafteo](#sistema-de-crafteo)
+- [Sistema de Fundición](#sistema-de-fundición)
+- [Variables del Sistema](#variables-del-sistema)
+
+---
+
+## Introducción
+
+Este sistema de juegos permite crear y gestionar un RPG completo dentro de Discord, con items, tienda, combate, crafteo, y más.
+
+### Características Principales
+- ✅ Sistema de economía con múltiples monedas
+- ✅ Inventario por usuario y servidor
+- ✅ Tienda con ofertas temporales y límites
+- ✅ Sistema de crafteo con recetas
+- ✅ Áreas explorables con niveles
+- ✅ Enemigos (mobs) con drops
+- ✅ Sistema de fundición para procesar items
+- ✅ Mutaciones de items (mejoras/transformaciones)
+
+---
+
+## Estructura del Sistema
+
+### Directorios Principales
+
+```
+/src/commands/messages/game/
+├── itemCreate.ts      # Crear items
+├── itemEdit.ts        # Editar items existentes
+├── offerCreate.ts     # Crear ofertas de tienda
+├── offerEdit.ts       # Editar ofertas
+├── areaCreate.ts      # Crear áreas de juego
+├── areaEdit.ts        # Editar áreas
+├── areaNivel.ts       # Gestionar niveles de área
+├── mobEdit.ts         # Crear/editar mobs
+├── craftear.ts        # Sistema de crafteo
+├── comprar.ts         # Comprar en la tienda
+├── abrir.ts           # Abrir items consumibles
+└── ...
+
+/src/game/
+├── economy/           # Sistema de economía
+│   ├── service.ts
+│   └── types.ts
+├── combat/            # Sistema de combate
+│   ├── equipmentService.ts
+│   └── attacksWorker.ts
+├── consumables/       # Items consumibles
+│   └── service.ts
+├── cooldowns/         # Sistema de cooldowns
+│   └── service.ts
+├── minigames/         # Minijuegos
+│   ├── service.ts
+│   ├── types.ts
+│   └── seed.ts
+├── mutations/         # Mutaciones de items
+│   └── service.ts
+└── smelting/          # Sistema de fundición
+    └── service.ts
+```
+
+---
+
+## Creación de Items
+
+### Comando Base
+```
+!item-crear <key>
+```
+
+### Ejemplo Práctico
+
+**1. Crear un item básico (Poción de Vida)**
+```
+!item-crear pocion_vida
+```
+
+Esto abrirá un editor interactivo con los siguientes botones:
+
+#### 📝 **Base** - Información básica del item
+- **Key**: `pocion_vida` (identificador único)
+- **Name**: `Poción de Vida`
+- **Description**: `Restaura 50 HP al usuario`
+- **Type**: `consumable` (otros: `material`, `equipment`, `key_item`, `currency`)
+- **Rarity**: `common` (otros: `uncommon`, `rare`, `epic`, `legendary`, `mythic`)
+- **Stackable**: `true` (si se puede apilar en el inventario)
+- **Max Stack**: `99` (cantidad máxima por stack)
+
+#### 💎 **Valor Base**
+Define el valor del item en el sistema económico:
+```json
+{
+  "coins": 50,
+  "gems": 0
+}
+```
+
+#### 🎯 **Metadatos**
+Información adicional para items especiales:
+
+**Para consumibles:**
+```json
+{
+  "effect": "heal",
+  "amount": 50,
+  "duration": 0
+}
+```
+
+**Para equipamiento:**
+```json
+{
+  "slot": "weapon",
+  "attack": 10,
+  "defense": 0,
+  "speed": 5,
+  "level_req": 1
+}
+```
+
+**Para materiales de crafteo:**
+```json
+{
+  "craftable": true,
+  "tier": 1
+}
+```
+
+#### 🖼️ **Icono/Emoji**
+Emoji que representa el item: `🧪` o emoji personalizado `<:potion:123456789>`
+
+---
+
+### Tipos de Items Comunes
+
+#### 1. **Consumibles** (`consumable`)
+Items que se usan y desaparecen:
+- Pociones de vida/maná
+- Comida
+- Buffs temporales
+- Pergaminos de teletransporte
+
+**Ejemplo:**
+```json
+{
+  "type": "consumable",
+  "metadata": {
+    "effect": "heal_hp",
+    "amount": 100,
+    "cooldown": 30
+  }
+}
+```
+
+#### 2. **Materiales** (`material`)
+Recursos para crafteo:
+- Minerales
+- Madera
+- Hierbas
+- Partes de mobs
+
+**Ejemplo:**
+```json
+{
+  "type": "material",
+  "metadata": {
+    "tier": 1,
+    "craftable": true
+  }
+}
+```
+
+#### 3. **Equipamiento** (`equipment`)
+Items equipables:
+- Armas
+- Armaduras
+- Accesorios
+
+**Ejemplo:**
+```json
+{
+  "type": "equipment",
+  "metadata": {
+    "slot": "weapon",
+    "attack": 25,
+    "defense": 0,
+    "speed": 10,
+    "level_req": 5,
+    "durability": 100
+  }
+}
+```
+
+#### 4. **Items Clave** (`key_item`)
+Items importantes de quest:
+- Llaves
+- Documentos
+- Objetos de misión
+
+#### 5. **Moneda** (`currency`)
+Items que actúan como moneda:
+- Monedas alternativas
+- Tokens de eventos
+- Puntos de tienda
+
+---
+
+## Sistema de Tienda
+
+### Crear una Oferta
+
+```
+!offer-crear
+```
+
+### Estructura de una Oferta
+
+#### 📦 **Base**
+- **Item Key**: `pocion_vida` (el item que se vende)
+- **Enabled**: `true` (si la oferta está activa)
+
+#### 💰 **Precio (JSON)**
+Define cuánto cuesta el item:
+```json
+{
+  "coins": 100,
+  "gems": 0,
+  "items": {
+    "hierro": 5,
+    "madera": 10
+  }
+}
+```
+
+Puedes combinar:
+- `coins`: Moneda base
+- `gems`: Gemas premium
+- `items`: Otros items como pago (sistema de trueque)
+
+#### 🕒 **Ventana Temporal**
+Define cuándo está disponible la oferta:
+- **Inicio (ISO)**: `2025-10-05T00:00:00Z` (opcional)
+- **Fin (ISO)**: `2025-10-31T23:59:59Z` (opcional)
+
+Si no se especifica, la oferta está disponible siempre.
+
+#### 🎯 **Límites**
+Control de compras:
+- **Límite por usuario**: `5` (cada usuario puede comprar máximo 5)
+- **Stock global**: `100` (solo hay 100 unidades disponibles en total)
+
+Dejar vacío = sin límite
+
+#### 📝 **Metadata (JSON)**
+Información adicional:
+```json
+{
+  "featured": true,
+  "discount": 20,
+  "bundle": ["pocion_vida", "pocion_mana"],
+  "event": "halloween_2025"
+}
+```
+
+### Ejemplo Completo: Oferta de Halloween
+
+```
+Item: pocion_halloween
+Precio: { "coins": 50, "items": { "calabaza": 3 } }
+Ventana: 2025-10-01 hasta 2025-10-31
+Límite por usuario: 10
+Stock global: 500
+Metadata: { "event": "halloween_2025", "featured": true }
+```
+
+---
+
+## Áreas de Juego
+
+### Crear un Área
+
+```
+!area-crear <areaKey>
+```
+
+### Estructura de un Área
+
+#### 📍 **Base**
+- **Key**: `bosque_inicial` (identificador único)
+- **Name**: `Bosque Inicial`
+- **Description**: `Un bosque tranquilo perfecto para principiantes`
+- **Image URL**: URL de imagen del área (opcional)
+
+#### 🎮 **Configuración**
+```json
+{
+  "minLevel": 1,
+  "maxLevel": 5,
+  "danger": "low",
+  "biome": "forest"
+}
+```
+
+### Niveles de Área
+
+Cada área puede tener múltiples niveles con diferentes enemigos:
+
+```
+!area-nivel <areaKey>
+```
+
+**Ejemplo de configuración de nivel:**
+```json
+{
+  "level": 1,
+  "mobs": ["lobo_joven", "jabali_salvaje"],
+  "weights": [60, 40],
+  "bossKey": null,
+  "requirements": {
+    "minPlayerLevel": 1
+  }
+}
+```
+
+- **mobs**: Lista de keys de mobs que aparecen
+- **weights**: Probabilidad de aparición (en porcentaje)
+- **bossKey**: Mob especial de jefe (opcional)
+- **requirements**: Requisitos para acceder
+
+---
+
+## Mobs (Enemigos)
+
+### Crear/Editar un Mob
+
+```
+!mob-editar <mobKey>
+```
+
+### Estructura de un Mob
+
+#### 🎯 **Base**
+```json
+{
+  "key": "lobo_joven",
+  "name": "Lobo Joven",
+  "description": "Un lobo joven vagando por el bosque",
+  "image": "🐺",
+  "level": 2
+}
+```
+
+#### ⚔️ **Stats**
+```json
+{
+  "hp": 50,
+  "attack": 8,
+  "defense": 3,
+  "speed": 12,
+  "exp": 15
+}
+```
+
+#### 🎁 **Drops (Recompensas)**
+```json
+{
+  "coins": { "min": 5, "max": 15 },
+  "items": {
+    "piel_lobo": { "chance": 0.3, "min": 1, "max": 2 },
+    "colmillo": { "chance": 0.15, "min": 1, "max": 1 },
+    "carne_cruda": { "chance": 0.5, "min": 1, "max": 3 }
+  }
+}
+```
+
+- **coins**: Rango de monedas que dropea
+- **items**: Items con probabilidad de drop
+  - `chance`: Probabilidad (0.3 = 30%)
+  - `min`/`max`: Cantidad que dropea
+
+#### 🧬 **Comportamiento**
+```json
+{
+  "aggressive": true,
+  "pack": false,
+  "flee_threshold": 0.2,
+  "abilities": ["howl", "bite"]
+}
+```
+
+---
+
+## Sistema de Crafteo
+
+### Crear Items Crafteables
+
+Para que un item se pueda craftear, define su receta en los metadatos:
+
+**Ejemplo: Espada de Hierro**
+
+```json
+{
+  "type": "equipment",
+  "metadata": {
+    "slot": "weapon",
+    "attack": 15,
+    "craftable": true,
+    "recipe": {
+      "hierro": 5,
+      "madera": 2,
+      "cuero": 1
+    },
+    "crafting_time": 60,
+    "success_rate": 0.95,
+    "level_req": 3
+  }
+}
+```
+
+### Usar el Sistema de Crafteo
+
+```
+!craftear <itemKey>
+```
+
+El bot verificará:
+1. ✅ Que tengas los materiales necesarios
+2. ✅ Que cumplas el nivel requerido
+3. ✅ Calculará el éxito basado en `success_rate`
+4. ✅ Consumirá los materiales
+5. ✅ Te dará el item (si tiene éxito)
+
+---
+
+## Sistema de Fundición
+
+Procesa materiales crudos en refinados:
+
+### Configuración de Items Fundibles
+
+**Ejemplo: Hierro Crudo → Lingote de Hierro**
+
+**Item: `hierro_crudo`**
+```json
+{
+  "type": "material",
+  "metadata": {
+    "smeltable": true,
+    "smelts_into": "lingote_hierro",
+    "smelting_time": 30,
+    "fuel_cost": 1
+  }
+}
+```
+
+### Usar el Sistema
+
+```
+!fundir <itemKey> <cantidad>
+```
+
+Ejemplo:
+```
+!fundir hierro_crudo 10
+```
+
+Esto iniciará un trabajo de fundición que se completará después del tiempo especificado.
+
+---
+
+## Sistema de Mutaciones
+
+Transforma items en versiones mejoradas:
+
+### Configurar Mutaciones
+
+**Ejemplo: Espada de Hierro → Espada de Acero**
+
+```json
+{
+  "from_item": "espada_hierro",
+  "to_item": "espada_acero",
+  "requirements": {
+    "items": {
+      "carbon": 3,
+      "polvo_magico": 1
+    },
+    "coins": 500,
+    "level": 10
+  },
+  "success_rate": 0.8,
+  "keep_on_fail": false
+}
+```
+
+- **keep_on_fail**: Si `false`, pierdes el item si falla
+- **success_rate**: Probabilidad de éxito
+
+---
+
+## Variables del Sistema
+
+Puedes usar variables dinámicas en descripciones y nombres:
+
+### Variables de Usuario
+- `{user}` - Nombre del usuario
+- `{user.id}` - ID del usuario
+- `{user.mention}` - Mención del usuario
+- `{user.tag}` - Usuario#1234
+- `{user.level}` - Nivel del jugador
+- `{user.exp}` - Experiencia del jugador
+- `{user.coins}` - Monedas del jugador
+- `{user.gems}` - Gemas del jugador
+
+### Variables de Servidor
+- `{guild}` - Nombre del servidor
+- `{guild.id}` - ID del servidor
+- `{guild.members}` - Cantidad de miembros
+- `{guild.owner}` - Dueño del servidor
+
+### Variables de Item
+- `{item.name}` - Nombre del item
+- `{item.count}` - Cantidad en inventario
+- `{item.value}` - Valor del item
+
+### Ejemplo de Uso
+
+**Descripción dinámica:**
+```
+"¡{user}, has encontrado {item.name}! Ahora tienes {item.count} en tu inventario."
+```
+
+**Resultado:**
+```
+"¡Shni, has encontrado Poción de Vida! Ahora tienes 15 en tu inventario."
+```
+
+---
+
+## Comandos Útiles
+
+### Gestión de Items
+- `!item-crear <key>` - Crear nuevo item
+- `!item-editar <key>` - Editar item existente
+- `!inventario` - Ver tu inventario
+- `!usar <item>` - Usar un item consumible
+
+### Economía
+- `!monedas` - Ver tus monedas
+- `!daily` - Recompensa diaria
+- `!dar <@user> <item> <cantidad>` - Dar items a otro usuario
+
+### Tienda
+- `!tienda` - Ver la tienda
+- `!comprar <item> [cantidad]` - Comprar items
+- `!offer-crear` - Crear oferta (admin)
+- `!offer-editar <id>` - Editar oferta (admin)
+
+### Combate
+- `!explorar <area>` - Explorar un área
+- `!atacar` - Atacar al mob actual
+- `!huir` - Intentar huir del combate
+- `!equipar <item>` - Equipar un item
+
+### Crafteo
+- `!craftear <item>` - Craftear un item
+- `!receta <item>` - Ver la receta de un item
+- `!fundir <item> <cantidad>` - Fundir materiales
+
+### Áreas
+- `!area-crear <key>` - Crear área (admin)
+- `!area-editar <key>` - Editar área (admin)
+- `!area-nivel <key>` - Configurar niveles (admin)
+- `!areas` - Ver áreas disponibles
+
+---
+
+## Tips y Mejores Prácticas
+
+### 1. **Nomenclatura de Keys**
+Usa nombres descriptivos y sin espacios:
+- ✅ `pocion_vida_grande`
+- ✅ `espada_hierro_t2`
+- ❌ `Poción de Vida Grande` (evitar espacios y mayúsculas)
+
+### 2. **Balance Económico**
+- Items comunes: 10-100 coins
+- Items raros: 100-1000 coins
+- Items épicos: 1000-10000 coins
+- Items legendarios: 10000+ coins
+
+### 3. **Drop Rates Recomendados**
+- Comunes: 50-80%
+- Raros: 20-30%
+- Épicos: 5-10%
+- Legendarios: 1-3%
+- Míticos: <1%
+
+### 4. **Organización de Áreas**
+Crea áreas progresivas:
+1. **Área Inicial** (Nivel 1-5): Mobs fáciles, drops básicos
+2. **Área Intermedia** (Nivel 6-15): Mobs moderados, mejores drops
+3. **Área Avanzada** (Nivel 16-30): Mobs difíciles, drops raros
+4. **Área End-Game** (Nivel 31+): Jefes, drops legendarios
+
+### 5. **Testing**
+Antes de lanzar al público:
+- ✅ Prueba todas las recetas de crafteo
+- ✅ Verifica que los precios sean balanceados
+- ✅ Asegúrate de que los mobs no sean muy fáciles/difíciles
+- ✅ Revisa que todos los items tengan iconos
+- ✅ Prueba las ofertas temporales
+
+---
+
+## Solución de Problemas
+
+### "Item no encontrado"
+- Verifica que la key esté escrita correctamente
+- Asegúrate de que el item exista en la base de datos
+- Revisa si el item es específico del servidor
+
+### "No tienes suficientes materiales"
+- Usa `!inventario` para verificar tus items
+- Asegúrate de tener todos los materiales de la receta
+
+### "No tienes nivel suficiente"
+- Usa `!perfil` para ver tu nivel actual
+- Combate más mobs para ganar experiencia
+
+### "La oferta no está disponible"
+- Verifica las fechas de la ventana temporal
+- Asegúrate de que la oferta esté habilitada
+- Revisa si alcanzaste el límite de compras
+
+---
+
+## Créditos
+
+Sistema creado para **Amayo Bot**  
+Documentación actualizada: Octubre 2025
+
+Para soporte adicional, contacta a los administradores del servidor.
+