From eae36f63e26c4e362e497d8cca2d701b2b30f125 Mon Sep 17 00:00:00 2001 From: shni Date: Sun, 5 Oct 2025 23:18:13 -0500 Subject: [PATCH] fix: correct HTML structure by moving - - - - - Amayo Docs | Guía de Contenido - - - - - - - -
-
-

Documentación de Contenido Amayo

-

- Crea y gestiona items, enemigos, áreas, niveles, logros, misiones, cofres, - mutaciones y más usando los comandos del bot. Esta guía reúne los flujos - completos y plantillas listas para copiar. -

-
- Empezar ahora - -
-
-
- Actualizado: 5 Oct 2025 - Compatible con DisplayComponents V2 -
-
- -
- - -
-
-

Conceptos básicos

-

- Toda pieza de contenido en Amayo se identifica mediante una key - única. Estas keys se usan en comandos, relaciones y validaciones. Usa un - formato consistente como categoria_nombre (ej: - item_iron_sword). -

-
-
-

Permisos necesarios

-
    -
  • Permiso de Discord Administrar Servidor.
    • -
  • O bien un rol Staff configurado para los comandos del bot.
    • -
-
-
-

Sistema de pesos

-

- Al definir tablas de recompensas o aparición de enemigos, usa un campo - weight. Cuanto mayor sea el peso, mayor la probabilidad de ser - seleccionado. -

- 
{ "itemKey": "iron_ore", "weight": 10 }
-{ "itemKey": "gold_ore", "weight": 3 }
-
-
-
- -
-

Items (EconomyItem)

-

- Administra todo el inventario del juego. Usa !item-crear para abrir - el editor interactivo y completa cada pestaña antes de guardar. -

-
-
-

Comandos clave

-
    -
  • !item-crear <key> — Crear un item nuevo.
    • -
  • !item-editar <key> — Editar un item existente.
    • -
  • !items-lista [página] — Ver listado paginado.
    • -
  • !item-ver <key> — Ver detalles completos.
    • -
  • !item-eliminar <key> — Eliminar un item.
    • -
-
-
-

Campos del modal Base

-
    -
  • Nombre: Texto visible para jugadores.
    • -
  • Descripción: Lore o efectos.
    • -
  • Categoría: Agrupa items (ej. weapons).
    • -
  • Icon URL: Imagen opcional.
    • -
  • - Stackable y Máx inventario: Usa - true,10, false,1 o deja el límite vacío para - infinito. -
    • -
-
-
-
-

Props disponibles

-
-
- Herramientas (tool) - 
{
-  "tool": { "type": "pickaxe|rod|sword|bow|halberd|net", "tier": 1 }
-}
-

- Define el tipo de actividad que habilita tu item. El campo - tier controla los requisitos mínimos de áreas y minijuegos. -

-
-
- Durabilidad (breakable) - 
{
-  "breakable": {
-    "enabled": true,
-    "maxDurability": 100,
-    "durabilityPerUse": 1
-  }
-}
-

- Sólo funciona con items no apilables. Ajusta la pérdida de - durabilidad por uso para balancear actividades. -

-
-
- Cofres (chest) - 
{
-  "chest": {
-    "enabled": true,
-    "rewards": [ ... ],
-    "consumeOnOpen": true
-  }
-}
-

- Permite definir loot tables internas, recompensas de monedas, items o roles. -

-
-
- Comida y pociones (food) - 
{
-  "food": {
-    "healHp": 50,
-    "healPercent": 25,
-    "cooldownSeconds": 60
-  }
-}
-

Útil para pociones curativas o consumibles con cooldown.

-
-
- Bonos de combate - 
{
-  "damage": 10,
-  "defense": 5,
-  "maxHpBonus": 20
-}
-

Configura stats extra para armas, armaduras o capas.

-
-
- Etiquetas y metadatos -

- Usa el modal Tags para añadir etiquetas separadas por coma, como - weapon,rare,crafteable. Sirven para filtrar o aplicar reglas. -

-
-
-
-
- -
-

Mobs (Enemigos)

-

- Los enemigos definen los encuentros durante minijuegos y niveles de área. Se - crean con !mob-crear y usan stats y tablas de drop en formato JSON. -

-
-
-

Campos principales

-
    -
  • Base: Nombre y categoría opcional.
    • -
  • - Stats: Define attack, hp, - defense, xpReward. -
    • -
  • - Drops: Incluye draws y una tabla con premios - ponderados. -
    • -
-
-
-

Ejemplo de configuración

- 
{
-  "attack": 10,
-  "hp": 100,
-  "defense": 5,
-  "xpReward": 50
-}
- 
{
-  "draws": 2,
-  "table": [
-    { "type": "coins", "amount": 50, "weight": 10 },
-    { "type": "item", "itemKey": "leather", "qty": 1, "weight": 5 }
-  ]
-}
-
-
-
- Tip: Usa !mobs-lista para auditar stats rápidamente y - !mob-ver <key> para revisar drops antes de activar un área. -
-
- -
-

Áreas de juego (GameArea)

-

- Las áreas definen dónde se desarrollan las actividades principales (minar, - pescar, pelear, plantar). Cada área puede tener múltiples niveles configurables. -

-
-
-

Modal Base

-
    -
  • Nombre: Ej. Caverna de Hierro.
    • -
  • Tipo: MINE, LAGOON, - FIGHT o FARM.
    • -
-
-
-

Modal Config (JSON)

- 
{
-  "cooldownSeconds": 60,
-  "description": "Una mina profunda",
-  "icon": "⛏️"
-}
-

El ícono se mostrará en las tarjetas generadas por DisplayComponents.

-
-
-
- Recuerda: Si eliminas un área con !area-eliminar, - revisa niveles asociados para evitar referencias rotas. -
-
- -
-

Niveles de área (GameAreaLevel)

-

- Cada nivel controla requisitos, mobs, recompensas y vigencia. Gestiona niveles con - !area-nivel <areaKey> <level>. -

-
-
-

Requisitos

- 
{
-  "tool": {
-    "required": true,
-    "toolType": "pickaxe",
-    "minTier": 2,
-    "allowedKeys": ["iron_pickaxe", "diamond_pickaxe"]
-  }
-}
-

- Sirve para validar herramientas necesarias. Combínalo con los tiers definidos - en los items. -

-
-
-

Recompensas

- 
{
-  "draws": 3,
-  "table": [
-    { "type": "coins", "amount": 100, "weight": 10 },
-    { "type": "item", "itemKey": "iron_ore", "qty": 2, "weight": 5 }
-  ]
-}
-

Define múltiples extracciones de la tabla con pesos personalizados.

-
-
-
-

Mobs y ventana

- 
{
-  "mobPool": {
-    "draws": 2,
-    "table": [
-      { "mobKey": "goblin", "weight": 10 },
-      { "mobKey": "troll", "weight": 3 }
-    ]
-  }
-}
- 
{
-  "window": {
-    "from": "2025-01-01T00:00:00Z",
-    "to": "2025-01-31T23:59:59Z"
-  }
-}
-
-
- -
-

Ofertas de tienda (ShopOffer)

-

- Usa !offer-crear para lanzar nuevas ofertas con stock limitado, - precios compuestos y ventanas temporales. -

-
-
-

Precio (JSON)

- 
{
-  "coins": 100,
-  "items": [
-    { "itemKey": "iron_ore", "qty": 5 },
-    { "itemKey": "wood", "qty": 10 }
-  ]
-}
-
-
-

Límites y ventana

-
    -
  • Límite por usuario: Máximo por jugador.
    • -
  • Stock global: Total disponible.
    • -
  • Ventana: Fechas ISO de inicio y fin.
    • -
-
-
-
- -
-

Logros

-

- Motiva a los jugadores con hitos permanentes. Crea logros con - !logro-crear y configúralos usando el editor DisplayComponents. -

-
-
-

Requisitos comunes

-
    -
  • collect_items: Recolectar items específicos.
    • -
  • complete_missions: Completar misiones listadas.
    • -
  • reach_level: Alcanzar cierto nivel o racha.
    • -
  • stat_value: Llegar a un valor en estadísticas.
    • -
-
-
-

Recompensas posibles

-
    -
  • Monedas
    • -
  • Items entregados automáticamente
    • -
  • Roles (usa ID de Discord)
    • -
  • Puntos de logro
    • -
-
-
-
- Nota: Usa !logros-lista para auditar logros y - !logro-ver <key> para validar estructura antes de publicarlos. -
-
- -
-

Misiones

-

- Las misiones permiten objetivos diarios, semanales o repetibles. Adminístralas con - !mision-crear y !misiones-lista. -

-
-
-

Tipos de misión

-
    -
  • daily: Reinicia cada día.
    • -
  • weekly: Reinicia cada semana.
    • -
  • one_time: Se completa una vez.
    • -
  • repeatable: Puede repetirse sin límite.
    • -
-
-
-

Requisitos combinables

-
    -
  • Consumir items o recursos.
    • -
  • Completar minijuegos específicos.
    • -
  • Derrotar mobs concretos.
    • -
  • Lograr cantidades de monedas.
    • -
-
-
-
- Tip: Aprovecha la ventana de disponibilidad para crear eventos - temáticos limitados. -
-
- -
-

Cofres y recompensas

-

- Configura cofres usando props chest en los items y define tablas de - recompensas con pesos. Ideal para loot boxes, recompensas diarias o drops raros. -

-
-
-

Recompensas soportadas

-
    -
  • Monedas (coins)
    • -
  • Items (usa itemKey y qty)
    • -
  • Roles de Discord (roleId)
    • -
-
-
-

Consejos

-
    -
  • Usa consumeOnOpen para cofres desechables.
    • -
  • Combina cofres con logros y eventos para mejores recompensas.
    • -
  • Define varias entradas con pesos distintos para crear rarezas.
    • -
-
-
-
- -
-

Crafteos

-

- Gestiona recetas desde la base de datos o crea comandos personalizados. El servicio - de economía incluye craftByProductKey para validar materiales y - entregar productos. -

-
    -
  • Define recetas en Prisma con entradas y productos.
    • -
  • - Usa misiones o eventos para desbloquear recetas temporales combinando props y - tags. -
    • -
  • - Considera usar craftingOnly: true en items que no se consiguen por - drops. -
    • -
-
- -
-

Mutaciones

-

- Las mutaciones permiten modificar items existentes con efectos adicionales (ej. - reforjar armas). Usa findMutationByKey y - applyMutationToInventory desde el servicio de economía. -

-
-
-

Políticas

- 
{
-  "mutationPolicy": {
-    "allowedKeys": ["fire_upgrade", "ice_upgrade"],
-    "deniedKeys": ["cursed_upgrade"]
-  }
-}
-
-
-

Sugerencias

-
    -
  • Crea mutaciones exclusivas por eventos.
    • -
  • Combínalas con logros o misiones épicas.
    • -
  • Controla conflictos usando deniedKeys.
    • -
-
-
-
- -
-

Pociones y consumibles

-

- Usa props food para crear pociones curativas, boosters temporales o - consumibles con cooldown. Complementa con misiones diarias o drops específicos. -

-
-
-

Ejemplo de poción

- 
{
-  "food": {
-    "healHp": 75,
-    "healPercent": 15,
-    "cooldownKey": "healing_potion",
-    "cooldownSeconds": 45
-  }
-}
-
-
-

Buenas prácticas

-
    -
  • Usa cooldownKey para compartir cooldown entre pociones similares.
    • -
  • Balancea healHp y healPercent para distintos niveles de jugador.
    • -
  • Combina con logros para recompensar uso estratégico.
    • -
-
-
-
- -
-

Herramientas y durabilidad

-

- La durabilidad se administra a través de la combinación de props tool - y breakable. Para que un item pierda durabilidad, debe ser - no apilable (stackable=false en el modal Base). -

-
    -
  • La función reduceToolDurability descuenta - durabilityPerUse tras cada minijuego.
    • -
  • Cuando la durabilidad llega a 0, el item se elimina del inventario.
    • -
  • Si breakable.enabled es false, la herramienta es indestructible.
    • -
  • - Usa tiers para bloquear áreas avanzadas. Ejemplo: Un área puede requerir una - herramienta pickaxe con tier >= 2. -
    • -
-
- Importante: Después de cambiar items apilables a no apilables, - recrea el item en los inventarios existentes para evitar stacks rotos. -
-
- -
-

Servicios del sistema

-
-
-

Economy Service

-
    -
  • findItemByKey y addItemByKey
    • -
  • consumeItemByKey y getInventoryEntry
    • -
  • craftByProductKey y buyFromOffer
    • -
  • findMutationByKey y applyMutationToInventory
    • -
-
-
-

Minigames Service

-
    -
  • runMinigame para ejecutar cualquier actividad.
    • -
  • runMining y runFishing como atajos.
    • -
  • Valida cooldowns, requisitos de herramientas y entrega recompensas.
    • -
  • Reduce durabilidad automáticamente cuando corresponde.
    • -
-
-
-
- -
-

Preguntas frecuentes

-
- ¿Qué pasa si olvido definir stackable? -

Por defecto los items son apilables. Si tu herramienta pierde durabilidad, asegúrate de marcarla como no apilable en el modal Base.

-
-
- ¿Cómo pruebo mis configuraciones? -

Usa comandos de prueba en un servidor privado con el bot y confirma con !player, !stats y !inventario.

-
-
- ¿Puedo clonar contenido entre servidores? -

Sí. Los items globales están disponibles en todos los servidores; los locales se limitan a su guild. Usa las herramientas de exportación de Prisma si necesitas migraciones masivas.

-
-
- ¿Cómo despliego esta documentación? -

Consulta las instrucciones en server/README.md para publicar en Heroku como app independiente.

-
-
-
-
- -