From c446334689d11276cd271499c1ae7d4ebc609296 Mon Sep 17 00:00:00 2001
From: shni <am7777336@gmail.com>
Date: Sun, 5 Oct 2025 03:42:48 -0500
Subject: [PATCH] feat(economy): add comprehensive user guide for game content
 creation

---
 GUIA_DE_USUARIO.md | 711 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 711 insertions(+)
 create mode 100644 GUIA_DE_USUARIO.md

diff --git a/GUIA_DE_USUARIO.md b/GUIA_DE_USUARIO.md
new file mode 100644
index 0000000..a8f3dc7
--- /dev/null
+++ b/GUIA_DE_USUARIO.md
@@ -0,0 +1,711 @@
+# 🎮 Guía de Usuario - Sistema de Economía y Minijuegos
+
+> **Bienvenido a la guía completa para crear contenido de juego en tu servidor de Discord**
+
+Esta guía te enseñará cómo crear items, enemigos, áreas de juego y ofertas de tienda usando comandos simples de Discord. No necesitas saber programación, solo seguir los pasos.
+
+---
+
+## 📋 Tabla de Contenidos
+
+1. [Requisitos Previos](#requisitos-previos)
+2. [Conceptos Básicos](#conceptos-básicos)
+3. [Creando tu Primer Item](#creando-items)
+4. [Creando Enemigos](#creando-enemigos)
+5. [Configurando Áreas de Juego](#configurando-áreas)
+6. [Configurando Niveles](#configurando-niveles)
+7. [Creando Ofertas de Tienda](#creando-ofertas)
+8. [Ejemplos Prácticos](#ejemplos-prácticos)
+9. [Preguntas Frecuentes](#preguntas-frecuentes)
+
+---
+
+## 🔑 Requisitos Previos {#requisitos-previos}
+
+Para usar los comandos de creación de contenido, necesitas:
+- Tener el permiso **"Administrar Servidor"** en Discord, **O**
+- Tener un rol de Staff configurado en tu servidor
+
+---
+
+## 💡 Conceptos Básicos {#conceptos-básicos}
+
+### ¿Qué es una "key"?
+Una **key** es un identificador único para cada elemento que crees. Piénsalo como el "nombre interno" del elemento.
+
+**Ejemplos de keys:**
+- `iron_sword` (para una espada de hierro)
+- `health_potion` (para una poción de vida)
+- `cave_spider` (para un enemigo araña)
+
+**⚠️ Importante:** Las keys no pueden repetirse y deben ser únicas.
+
+### Sistema de Pesos (Weights)
+Cuando configuras recompensas o enemigos que aparecen, usas un sistema de **pesos** para decidir qué tan común es cada cosa.
+
+**Ejemplo:**
+```json
+{ "itemKey": "iron_ore", "weight": 10 }  ← Aparece 10 veces de cada 13
+{ "itemKey": "gold_ore", "weight": 3 }   ← Aparece 3 veces de cada 13
+```
+
+Cuanto **mayor** sea el número, **más probable** es que aparezca.
+
+---
+
+## 🎒 Creando Items {#creando-items}
+
+### Paso 1: Iniciar el Editor
+Escribe en Discord:
+```
+!item-crear <key>
+```
+
+**Ejemplo:**
+```
+!item-crear iron_sword
+```
+
+### Paso 2: Configurar la Base
+Haz clic en el botón **"Base"** y llena los campos:
+
+| Campo | Descripción | Ejemplo |
+|-------|-------------|---------|
+| **Nombre** | Nombre visible del item | `Espada de Hierro` |
+| **Descripción** | Descripción del item | `Una espada forjada con hierro resistente` |
+| **Categoría** | Tipo de item | `weapons` |
+| **Icon URL** | URL de una imagen (opcional) | `https://...` |
+| **Stackable y Máx** | Si se apila y máximo por inventario | `true,10` o `false,1` |
+
+#### ¿Qué significa "Stackable"?
+- **`true,10`** = Se pueden apilar hasta 10 unidades del mismo item
+- **`false,1`** = Solo puedes tener 1 unidad (común para armas/herramientas)
+- **`true,`** (dejar vacío el número) = Apilable sin límite
+
+### Paso 3: Agregar Tags (Opcional)
+Los tags te ayudan a organizar tus items. Haz clic en **"Tags"** y escribe:
+```
+weapon, rare, crafteable
+```
+
+### Paso 4: Configurar Propiedades Avanzadas (Props)
+Aquí defines qué hace especial a tu item. Haz clic en **"Props (JSON)"**.
+
+#### 🛠️ **Props para Herramientas**
+
+Usa esto si tu item es una herramienta (pico, caña, espada, etc.):
+
+```json
+{
+  "tool": {
+    "type": "pickaxe",
+    "tier": 2
+  },
+  "breakable": {
+    "enabled": true,
+    "maxDurability": 150,
+    "durabilityPerUse": 1
+  }
+}
+```
+
+**Tipos de herramientas disponibles:**
+- `pickaxe` (pico para minar)
+- `rod` (caña para pescar)
+- `sword` (espada para pelear)
+- `bow` (arco)
+- `halberd` (alabarda)
+- `net` (red)
+
+**Durabilidad:**
+- `maxDurability`: Cuántos usos tiene antes de romperse
+- `durabilityPerUse`: Cuánta durabilidad pierde por uso (normalmente 1)
+
+#### ⚔️ **Props para Armas/Armaduras**
+
+```json
+{
+  "damage": 15,
+  "defense": 0
+}
+```
+
+- `damage`: Daño que hace el arma
+- `defense`: Defensa que da la armadura
+- `maxHpBonus`: HP extra que otorga (para capas)
+
+#### 🍖 **Props para Comida/Pociones**
+
+```json
+{
+  "food": {
+    "healHp": 50,
+    "cooldownSeconds": 30
+  }
+}
+```
+
+- `healHp`: Cuánta vida cura
+- `healPercent`: Porcentaje de vida que cura (opcional)
+- `cooldownSeconds`: Segundos antes de poder usar otra vez
+
+#### 📦 **Props para Cofres**
+
+Los cofres pueden dar monedas, items o roles cuando se abren:
+
+```json
+{
+  "chest": {
+    "enabled": true,
+    "rewards": [
+      { "type": "coins", "amount": 100 },
+      { "type": "item", "itemKey": "iron_ore", "qty": 5 },
+      { "type": "role", "roleId": "123456789012345678" }
+    ],
+    "consumeOnOpen": true
+  }
+}
+```
+
+- `consumeOnOpen`: Si es `true`, el cofre se consume al abrirse
+
+### Paso 5: Guardar
+Haz clic en **"Guardar"** y ¡listo! Tu item ha sido creado.
+
+---
+
+## 👹 Creando Enemigos (Mobs) {#creando-enemigos}
+
+### Paso 1: Iniciar el Editor
+```
+!mob-crear <key>
+```
+
+**Ejemplo:**
+```
+!mob-crear goblin
+```
+
+### Paso 2: Configurar Base
+Haz clic en **"Base"**:
+- **Nombre:** `Goblin`
+- **Categoría:** `enemies` (opcional)
+
+### Paso 3: Configurar Stats
+Haz clic en **"Stats (JSON)"**:
+
+```json
+{
+  "attack": 10,
+  "hp": 50,
+  "defense": 3,
+  "xpReward": 25
+}
+```
+
+- `attack`: Daño que hace el enemigo
+- `hp`: Vida del enemigo
+- `defense`: Defensa del enemigo
+- `xpReward`: Experiencia que da al derrotarlo
+
+### Paso 4: Configurar Drops (Recompensas)
+Haz clic en **"Drops (JSON)"**:
+
+```json
+{
+  "draws": 2,
+  "table": [
+    { "type": "coins", "amount": 20, "weight": 10 },
+    { "type": "item", "itemKey": "leather", "qty": 1, "weight": 5 },
+    { "type": "item", "itemKey": "goblin_tooth", "qty": 1, "weight": 2 }
+  ]
+}
+```
+
+- `draws`: Cuántos premios saca de la tabla
+- `table`: Lista de posibles premios con su peso (probabilidad)
+
+**En este ejemplo:**
+- Hace 2 extracciones
+- Más probable: 20 monedas (peso 10)
+- Medianamente probable: 1 cuero (peso 5)
+- Poco probable: 1 diente de goblin (peso 2)
+
+### Paso 5: Guardar
+Haz clic en **"Guardar"**.
+
+---
+
+## 🗺️ Configurando Áreas de Juego {#configurando-áreas}
+
+Las áreas son lugares donde los jugadores pueden realizar actividades como minar, pescar o pelear.
+
+### Paso 1: Crear el Área
+```
+!area-crear <key>
+```
+
+**Ejemplo:**
+```
+!area-crear mine.iron_cavern
+```
+
+### Paso 2: Configurar Base
+Haz clic en **"Base"**:
+- **Nombre:** `Caverna de Hierro`
+- **Tipo:** Elige uno:
+  - `MINE` (minar)
+  - `LAGOON` (pescar)
+  - `FIGHT` (pelear)
+  - `FARM` (plantar)
+
+### Paso 3: Configurar Config
+Haz clic en **"Config (JSON)"**:
+
+```json
+{
+  "cooldownSeconds": 60,
+  "description": "Una profunda caverna llena de minerales de hierro",
+  "icon": "⛏️"
+}
+```
+
+- `cooldownSeconds`: Segundos que deben esperar entre usos
+
+### Paso 4: Guardar
+Haz clic en **"Guardar"**.
+
+---
+
+## 📊 Configurando Niveles de Área {#configurando-niveles}
+
+Los niveles son las "dificultades" de cada área. Cada nivel puede tener diferentes requisitos, recompensas y enemigos.
+
+### Paso 1: Crear el Nivel
+```
+!area-nivel <key-del-área> <número-de-nivel>
+```
+
+**Ejemplo:**
+```
+!area-nivel mine.iron_cavern 1
+```
+
+### Paso 2: Configurar Requisitos
+Haz clic en **"Requisitos"**:
+
+```json
+{
+  "tool": {
+    "required": true,
+    "toolType": "pickaxe",
+    "minTier": 2
+  }
+}
+```
+
+**Significado:**
+- Es **obligatorio** tener un pico (`required: true`)
+- Debe ser un pico de nivel 2 o superior (`minTier: 2`)
+
+**Si no quieres requisitos:**
+```json
+{}
+```
+
+### Paso 3: Configurar Recompensas
+Haz clic en **"Recompensas"**:
+
+```json
+{
+  "draws": 3,
+  "table": [
+    { "type": "coins", "amount": 50, "weight": 10 },
+    { "type": "item", "itemKey": "iron_ore", "qty": 2, "weight": 8 },
+    { "type": "item", "itemKey": "gold_ore", "qty": 1, "weight": 2 }
+  ]
+}
+```
+
+**En este ejemplo:**
+- Hace 3 extracciones de la tabla
+- Más probable: 50 monedas
+- Probable: 2 minerales de hierro
+- Poco probable: 1 mineral de oro
+
+### Paso 4: Configurar Mobs (Enemigos que Aparecen)
+Haz clic en **"Mobs"**:
+
+```json
+{
+  "draws": 1,
+  "table": [
+    { "mobKey": "cave_spider", "weight": 10 },
+    { "mobKey": "bat", "weight": 5 },
+    { "mobKey": "cave_troll", "weight": 1 }
+  ]
+}
+```
+
+- `draws`: Cuántos enemigos pueden aparecer (en este caso, 1)
+- Más probable: araña de cueva
+- Menos probable: murciélago
+- Muy poco probable: troll de cueva
+
+**Si no quieres enemigos:**
+```json
+{
+  "draws": 0,
+  "table": []
+}
+```
+
+### Paso 5: Configurar Ventana de Disponibilidad (Opcional)
+Si quieres que el nivel solo esté disponible en ciertas fechas, haz clic en **"Ventana"**:
+
+- **Desde:** `2025-12-01T00:00:00Z` (formato ISO)
+- **Hasta:** `2025-12-31T23:59:59Z`
+
+**Deja en blanco si quieres que esté siempre disponible.**
+
+### Paso 6: Guardar
+Haz clic en **"Guardar"**.
+
+---
+
+## 🏪 Creando Ofertas de Tienda {#creando-ofertas}
+
+Las ofertas permiten vender items a los jugadores.
+
+### Paso 1: Crear la Oferta
+```
+!offer-crear
+```
+
+### Paso 2: Configurar Base
+Haz clic en **"Base"**:
+- **Item Key:** `iron_sword` (el item que quieres vender)
+- **Habilitada?:** `true` (o `false` para deshabilitarla)
+
+### Paso 3: Configurar Precio
+Haz clic en **"Precio (JSON)"**:
+
+#### Precio solo en monedas:
+```json
+{
+  "coins": 100
+}
+```
+
+#### Precio en monedas e items:
+```json
+{
+  "coins": 50,
+  "items": [
+    { "itemKey": "iron_ore", "qty": 5 },
+    { "itemKey": "wood", "qty": 10 }
+  ]
+}
+```
+
+**Significado:** Cuesta 50 monedas + 5 minerales de hierro + 10 maderas.
+
+### Paso 4: Configurar Límites (Opcional)
+Haz clic en **"Límites"**:
+
+- **Límite por usuario:** `5` (cada jugador puede comprar máximo 5)
+- **Stock global:** `100` (solo hay 100 unidades disponibles en total)
+
+**Deja en blanco para ilimitado.**
+
+### Paso 5: Configurar Ventana (Opcional)
+Si es una oferta temporal (como evento), haz clic en **"Ventana"**:
+
+- **Inicio:** `2025-12-20T00:00:00Z`
+- **Fin:** `2025-12-25T23:59:59Z`
+
+### Paso 6: Guardar
+Haz clic en **"Guardar"**.
+
+---
+
+## 📚 Ejemplos Prácticos {#ejemplos-prácticos}
+
+### Ejemplo 1: Sistema de Minería Completo
+
+#### 1. Crear el Pico de Madera
+```
+!item-crear wooden_pickaxe
+```
+
+**Base:**
+- Nombre: `Pico de Madera`
+- Descripción: `Un pico básico para empezar a minar`
+- Stackable: `false,1`
+
+**Props:**
+```json
+{
+  "tool": { "type": "pickaxe", "tier": 1 },
+  "breakable": { "enabled": true, "maxDurability": 50, "durabilityPerUse": 1 }
+}
+```
+
+#### 2. Crear el Mineral de Cobre
+```
+!item-crear copper_ore
+```
+
+**Base:**
+- Nombre: `Mineral de Cobre`
+- Descripción: `Un mineral común encontrado en las minas`
+- Stackable: `true,999`
+
+**Props:**
+```json
+{
+  "craftingOnly": false
+}
+```
+
+#### 3. Crear el Área de Mina
+```
+!area-crear mine.starter
+```
+
+**Base:**
+- Nombre: `Mina Inicial`
+- Tipo: `MINE`
+
+**Config:**
+```json
+{
+  "cooldownSeconds": 30,
+  "icon": "⛏️"
+}
+```
+
+#### 4. Crear Nivel 1 de la Mina
+```
+!area-nivel mine.starter 1
+```
+
+**Requisitos:**
+```json
+{
+  "tool": { "required": true, "toolType": "pickaxe", "minTier": 1 }
+}
+```
+
+**Recompensas:**
+```json
+{
+  "draws": 2,
+  "table": [
+    { "type": "coins", "amount": 10, "weight": 10 },
+    { "type": "item", "itemKey": "copper_ore", "qty": 1, "weight": 8 }
+  ]
+}
+```
+
+**Mobs:**
+```json
+{
+  "draws": 0,
+  "table": []
+}
+```
+
+---
+
+### Ejemplo 2: Cofre de Recompensa Diaria
+
+```
+!item-crear daily_chest
+```
+
+**Base:**
+- Nombre: `Cofre Diario`
+- Descripción: `Un cofre que contiene recompensas aleatorias`
+- Stackable: `true,10`
+
+**Props:**
+```json
+{
+  "chest": {
+    "enabled": true,
+    "rewards": [
+      { "type": "coins", "amount": 500 },
+      { "type": "item", "itemKey": "health_potion", "qty": 3 }
+    ],
+    "consumeOnOpen": true
+  }
+}
+```
+
+---
+
+### Ejemplo 3: Espada Legendaria
+
+```
+!item-crear legendary_sword
+```
+
+**Base:**
+- Nombre: `⚔️ Espada Legendaria de los Dragones`
+- Descripción: `Una espada forjada con escamas de dragón. Aumenta tu poder de ataque en 50 puntos.`
+- Categoría: `legendary_weapons`
+- Stackable: `false,1`
+
+**Tags:**
+```
+legendary, weapon, sword, dragon
+```
+
+**Props:**
+```json
+{
+  "damage": 50,
+  "tool": { "type": "sword", "tier": 5 },
+  "breakable": { "enabled": false }
+}
+```
+
+---
+
+### Ejemplo 4: Enemigo Boss
+
+```
+!mob-crear dragon_boss
+```
+
+**Base:**
+- Nombre: `🐉 Dragón Ancestral`
+- Categoría: `boss`
+
+**Stats:**
+```json
+{
+  "attack": 50,
+  "hp": 1000,
+  "defense": 30,
+  "xpReward": 1000
+}
+```
+
+**Drops:**
+```json
+{
+  "draws": 5,
+  "table": [
+    { "type": "coins", "amount": 1000, "weight": 10 },
+    { "type": "item", "itemKey": "dragon_scale", "qty": 3, "weight": 8 },
+    { "type": "item", "itemKey": "legendary_sword", "qty": 1, "weight": 1 }
+  ]
+}
+```
+
+---
+
+## ❓ Preguntas Frecuentes {#preguntas-frecuentes}
+
+### ¿Puedo editar un item después de crearlo?
+Sí, usa el comando:
+```
+!item-editar <key>
+```
+
+### ¿Cómo elimino un item?
+Actualmente debes contactar a un administrador del bot o hacerlo directamente desde la base de datos.
+
+### ¿Qué formato tienen las fechas ISO?
+El formato ISO es: `YYYY-MM-DDTHH:MM:SSZ`
+
+**Ejemplos:**
+- `2025-01-15T00:00:00Z` (15 de enero de 2025 a las 00:00 UTC)
+- `2025-12-25T23:59:59Z` (25 de diciembre de 2025 a las 23:59 UTC)
+
+### ¿Puedo crear items globales para todos los servidores?
+Solo los administradores del bot pueden crear items globales. Los items que crees estarán limitados a tu servidor.
+
+### ¿Cuántos niveles puedo crear por área?
+No hay límite técnico, pero se recomienda entre 5-10 niveles por área para mantener la progresión balanceada.
+
+### ¿Qué pasa si un jugador no tiene la herramienta requerida?
+El bot le mostrará un mensaje indicando qué herramienta necesita y de qué nivel.
+
+### ¿Cómo funcionan los pesos (weights)?
+Los pesos determinan la probabilidad relativa. Por ejemplo:
+- Item A (weight: 10) y Item B (weight: 5)
+- Item A tiene el doble de probabilidad de salir que Item B
+- Probabilidad de A: 10/15 = 66.7%
+- Probabilidad de B: 5/15 = 33.3%
+
+### ¿Puedo hacer que un item cure un porcentaje de vida en lugar de cantidad fija?
+Sí, usa `healPercent` en las props de food:
+```json
+{
+  "food": {
+    "healPercent": 50,
+    "cooldownSeconds": 60
+  }
+}
+```
+Esto curará el 50% de la vida máxima del jugador.
+
+### ¿Cómo hago que un nivel sea más difícil que otro?
+Aumenta:
+- El tier mínimo de herramienta requerida
+- El peso de enemigos más fuertes
+- Reduce el peso de recompensas comunes
+- Aumenta el cooldown del área
+
+### ¿Puedo combinar diferentes tipos de props en un item?
+Sí, puedes combinar múltiples props. Por ejemplo, un item que sea arma y herramienta:
+```json
+{
+  "tool": { "type": "sword", "tier": 3 },
+  "damage": 25,
+  "breakable": { "enabled": true, "maxDurability": 200, "durabilityPerUse": 1 }
+}
+```
+
+---
+
+## 🎓 Consejos Pro
+
+### Balanceo de Economía
+- Items iniciales: 10-100 monedas
+- Items raros: 500-1000 monedas
+- Items legendarios: 5000+ monedas
+
+### Progresión de Herramientas
+Tier recomendado:
+- Tier 1: Madera/Piedra
+- Tier 2: Cobre/Bronce
+- Tier 3: Hierro
+- Tier 4: Acero
+- Tier 5: Mithril/Legendario
+
+### Durabilidad Recomendada
+- Herramientas básicas: 50-100 usos
+- Herramientas intermedias: 150-300 usos
+- Herramientas avanzadas: 500+ usos
+
+### Cooldowns Recomendados
+- Actividades básicas: 30-60 segundos
+- Actividades intermedias: 2-5 minutos
+- Actividades difíciles: 10-30 minutos
+
+---
+
+## 📞 Soporte
+
+Si tienes problemas o preguntas:
+1. Verifica que tengas los permisos necesarios
+2. Revisa que tus JSONs estén bien formateados
+3. Contacta al soporte del bot en el servidor oficial
+
+---
+
+**¡Feliz creación de contenido! 🎉**