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,1o 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
drawsy 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 }
+ ]
+}!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, +FIGHToFARM.
+
Modal Config (JSON)
+{
+ "cooldownSeconds": 60,
+ "description": "Una mina profunda",
+ "icon": "⛏️"
+}El ícono se mostrará en las tarjetas generadas por DisplayComponents.
+!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 +
!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. +
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
itemKeyyqty)
+ - Roles de Discord (
roleId)
+
Consejos
+-
+
- Usa
consumeOnOpenpara 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: trueen 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
cooldownKeypara compartir cooldown entre pociones similares.
+ - Balancea
healHpyhealPercentpara 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
reduceToolDurabilitydescuenta +durabilityPerUsetras cada minijuego.
+ - Cuando la durabilidad llega a 0, el item se elimina del inventario. +
- Si
breakable.enabledesfalse, la herramienta es indestructible.
+ -
+ Usa tiers para bloquear áreas avanzadas. Ejemplo: Un área puede requerir una
+ herramienta
pickaxecontier >= 2. +
+
Servicios del sistema
+Economy Service
+-
+
findItemByKeyyaddItemByKey
+ consumeItemByKeyygetInventoryEntry
+ craftByProductKeyybuyFromOffer
+ findMutationByKeyyapplyMutationToInventory
+
Minigames Service
+-
+
runMinigamepara ejecutar cualquier actividad.
+ runMiningyrunFishingcomo 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.