amayo/GUIA_DE_USUARIO.md

🎮 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
2. Conceptos Básicos
3. Creando tu Primer Item
4. Creando Enemigos
5. Configurando Áreas de Juego
6. Configurando Niveles
7. Creando Ofertas de Tienda
8. Ejemplos Prácticos
9. Preguntas Frecuentes

---

🔑 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

¿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:

{ "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

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.):

{
  "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

{
  "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

{
  "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:

{
  "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)

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)":

{
  "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)":

{
  "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

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)":

{
  "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

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":

{
  "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:

{}

Paso 3: Configurar Recompensas

Haz clic en "Recompensas":

{
  "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":

{
  "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:

{
  "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

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:

{
  "coins": 100
}

Precio en monedas e items:

{
  "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

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:

{
  "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:

{
  "craftingOnly": false
}

3. Crear el Área de Mina

!area-crear mine.starter

Base:

• Nombre: Mina Inicial
• Tipo: MINE

Config:

{
  "cooldownSeconds": 30,
  "icon": "⛏️"
}

4. Crear Nivel 1 de la Mina

!area-nivel mine.starter 1

Requisitos:

{
  "tool": { "required": true, "toolType": "pickaxe", "minTier": 1 }
}

Recompensas:

{
  "draws": 2,
  "table": [
    { "type": "coins", "amount": 10, "weight": 10 },
    { "type": "item", "itemKey": "copper_ore", "qty": 1, "weight": 8 }
  ]
}

Mobs:

{
  "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:

{
  "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:

{
  "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:

{
  "attack": 50,
  "hp": 1000,
  "defense": 30,
  "xpReward": 1000
}

Drops:

{
  "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

¿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:

{
  "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:

{
  "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! 🎉