shni/amayo

Template

Fork 0

Files

shni 7967231865 feat(economy): update content creation documentation and improve editor validation

2025-10-05 03:36:11 -05:00

12 KiB

Raw Blame History

Documentación del Sistema de Economía y Minijuegos

Índice

Items (EconomyItem)
Mobs (Enemigos)
Áreas de Juego (GameArea)
Niveles de Área (GameAreaLevel)
Ofertas de Tienda (ShopOffer)s
Servicios del Sistema

Items (EconomyItem)

Crear Items

Comando: !item-crear <key-única>
Archivos: src/commands/messages/game/itemCreate.ts

Editor Interactivo

El comando abre un editor con botones:

Base: Configuración básica del item
Tags: Etiquetas del item (separadas por coma)
Props (JSON): Propiedades avanzadas en formato JSON
Guardar: Crea el item en la base de datos
Cancelar: Cancela la operación

Nombre (requerido): Nombre del item
Descripción: Descripción del item
Categoría: Categoría del item
Icon URL: URL de la imagen del item
Stackable y Máx inventario: Formato true,10 donde:
- Primer valor: true/false (si es apilable)
- Segundo valor: número máximo por inventario (vacío = ilimitado)

Lista de tags separados por comas (ej: weapon, rare, sword)

Objeto JSON con propiedades avanzadas. Plantilla:

{
  "tool": { "type": "pickaxe", "tier": 1 },
  "breakable": { "enabled": true, "maxDurability": 100, "durabilityPerUse": 1 },
  "chest": { "enabled": true, "rewards": [
    { "type": "coins", "amount": 100 },
    { "type": "item", "itemKey": "copper_ore", "qty": 5 }
  ], "consumeOnOpen": true },
  "eventCurrency": { "enabled": false, "eventKey": "" },
  "passiveEffects": [],
  "mutationPolicy": { "allowedKeys": [], "deniedKeys": [] },
  "craftingOnly": false,
  "food": { "healHp": 50, "cooldownSeconds": 60 },
  "damage": 10,
  "defense": 5,
  "maxHpBonus": 20
}

Editar Items

Comando: !item-editar <key-única>
Archivos: src/commands/messages/game/itemEdit.ts

Mismo editor que crear, pero carga los datos existentes del item.

Tipos de Props Disponibles

1. tool (Herramientas)

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

type: Tipo de herramienta (pico, caña, espada, arco, alabarda, red)
tier: Nivel/calidad de la herramienta (usado en requisitos de minijuegos)

2. breakable (Rompible/Durabilidad)

{
  "breakable": {
    "enabled": true,
    "maxDurability": 100,
    "durabilityPerUse": 1
  }
}

Para items no apilables que se desgastan con el uso.

3. chest (Cofres)

{
  "chest": {
    "enabled": true,
    "rewards": [
      { "type": "coins", "amount": 100 },
      { "type": "item", "itemKey": "iron_ore", "qty": 5 },
      { "type": "role", "roleId": "1234567890" }
    ],
    "consumeOnOpen": true
  }
}

4. food (Comida/Pociones)

{
  "food": {
    "healHp": 50,
    "healPercent": 25,
    "cooldownKey": "healing_potion",
    "cooldownSeconds": 60
  }
}

5. Stats de Combate

{
  "damage": 10,
  "defense": 5,
  "maxHpBonus": 20
}

Mobs (Enemigos)

Crear Mobs

Comando: !mob-crear <key-única>
Archivos: src/commands/messages/game/mobCreate.ts

Editor Interactivo

Base: Nombre y categoría
Stats (JSON): Estadísticas del mob
Drops (JSON): Tabla de recompensas al derrotar
Guardar/Cancelar

Nombre (requerido)
Categoría (opcional)

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

Editar Mobs

Comando: !mob-editar <key-única>
Archivos: src/commands/messages/game/mobEdit.ts

Mismo editor que crear, pero carga los datos existentes.

Áreas de Juego (GameArea)

Crear Áreas

Comando: !area-crear <key-única>
Archivos: src/commands/messages/game/areaCreate.ts

Las áreas representan lugares donde se pueden realizar actividades (minar, pescar, pelear, plantar).

Editor Interactivo

Base: Nombre y tipo
Config (JSON): Configuración del área
Meta (JSON): Metadatos adicionales
Guardar/Cancelar

Nombre (requerido)
Tipo (requerido): MINE, LAGOON, FIGHT, FARM

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

{
  "difficulty": "medium",
  "recommendedLevel": 5
}

Editar Áreas

Comando: !area-editar <key-única>
Archivos: src/commands/messages/game/areaEdit.ts

Niveles de Área (GameAreaLevel)

Crear/Editar Niveles

Comando: !area-nivel <areaKey> <level>
Archivos: src/commands/messages/game/areaNivel.ts

Los niveles definen requisitos, recompensas y mobs que aparecen en cada nivel de un área.

Editor Interactivo

Requisitos: Qué se necesita para acceder al nivel
Recompensas: Qué se obtiene al completarlo
Mobs: Qué enemigos pueden aparecer
Ventana: Fechas de disponibilidad
Guardar/Cancelar

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

required: Si es obligatorio tener herramienta
toolType: Tipo de herramienta requerida
minTier: Nivel mínimo de la herramienta
allowedKeys: Lista de items específicos permitidos

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

draws: Número de extracciones de la tabla
table: Array de recompensas ponderadas por weight

{
  "draws": 2,
  "table": [
    { "mobKey": "goblin", "weight": 10 },
    { "mobKey": "troll", "weight": 3 },
    { "mobKey": "dragon", "weight": 1 }
  ]
}

Desde (ISO): Fecha inicio (ej: 2025-01-01T00:00:00Z)
Hasta (ISO): Fecha fin (opcional)

Ofertas de Tienda (ShopOffer)

Crear Ofertas

Comando: !offer-crear
Archivos: src/commands/messages/game/offerCreate.ts

Editor Interactivo

Base: Item y estado
Precio (JSON): Costo de la oferta
Ventana: Fechas de disponibilidad
Límites: Stock y límite por usuario
Meta (JSON): Metadatos
Guardar/Cancelar

Item Key (requerido): Key del item a vender
Habilitada?: true/false

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

Inicio (ISO): Fecha inicio (opcional)
Fin (ISO): Fecha fin (opcional)

Límite por usuario: Máximo que puede comprar cada usuario (vacío = ilimitado)
Stock global: Stock total disponible (vacío = ilimitado)

Editar Ofertas

Comando: !offer-editar <offerId>
Archivos: src/commands/messages/game/offerEdit.ts

Servicios del Sistema

Economy Service

Archivo: src/game/economy/service.ts

Funciones Principales:

Gestión de Items:

findItemByKey(guildId, key): Busca un item por key (servidor o global)
addItemByKey(userId, guildId, itemKey, qty): Agrega items al inventario
consumeItemByKey(userId, guildId, itemKey, qty): Consume items del inventario
getInventoryEntry(userId, guildId, itemKey): Obtiene entrada de inventario

Wallet:

getOrCreateWallet(userId, guildId): Obtiene/crea billetera
adjustCoins(userId, guildId, delta): Ajusta monedas (positivo o negativo)

Cofres:

openChestByKey(userId, guildId, itemKey): Abre un cofre y entrega recompensas

Crafting:

craftByProductKey(userId, guildId, productKey): Craftea un item según receta

Compras:

buyFromOffer(userId, guildId, offerId, qty): Compra desde una oferta

Mutaciones:

findMutationByKey(guildId, key): Busca una mutación
applyMutationToInventory(userId, guildId, itemKey, mutationKey): Aplica mutación a item

Minigames Service

Archivo: src/game/minigames/service.ts

Funciones Principales:

Motor de Minijuegos:

runMinigame(userId, guildId, areaKey, level, opts): Ejecuta un minijuego
- Valida cooldowns
- Verifica requisitos (herramientas, etc.)
- Aplica recompensas
- Genera mobs
- Reduce durabilidad de herramientas
- Actualiza progreso del jugador

Atajos:

runMining(userId, guildId, level?, toolKey?): Ejecuta minería
runFishing(userId, guildId, level?, toolKey?): Ejecuta pesca

Herramientas:

findBestToolKey(userId, guildId, toolType, opts): Busca mejor herramienta del inventario
reduceToolDurability(userId, guildId, toolKey): Reduce durabilidad de herramienta

Equipment Service

Archivo: src/game/combat/equipmentService.ts

Funciones Principales:

Equipamiento:

getEquipment(userId, guildId): Obtiene equipamiento actual
setEquipmentSlot(userId, guildId, slot, itemId): Equipa item en slot (weapon/armor/cape)

Stats:

getEffectiveStats(userId, guildId): Calcula stats efectivos incluyendo:
- Daño de arma + mutaciones
- Defensa de armadura + mutaciones
- HP máximo de capa + mutaciones
- HP actual
adjustHP(userId, guildId, delta): Ajusta HP del jugador

Mutaciones:

Calcula bonos de mutaciones aplicadas a items equipados
Los bonos incluyen: damageBonus, defenseBonus, maxHpBonus

Tipos de Datos Importantes

ItemProps (src/game/economy/types.ts:74-96)

Propiedades opcionales de items:

tool: Metadatos de herramienta
breakable: Configuración de durabilidad
chest: Configuración de cofre
food: Configuración de comida/poción
eventCurrency: Moneda de evento
passiveEffects: Efectos pasivos
mutationPolicy: Política de mutaciones
craftingOnly: Solo para crafteo
damage/defense/maxHpBonus: Stats de combate
availableFrom/To: Ventana de disponibilidad
usableFrom/To: Ventana de uso

Price (src/game/economy/types.ts:10-14)

Precio de ofertas:

{
  coins?: number;
  items?: Array<{ itemKey?: string; itemId?: string; qty: number }>;
}

LevelRequirements (src/game/minigames/types.ts:11-15)

Requisitos para niveles de área:

{
  tool?: {
    required?: boolean;
    toolType?: string;
    minTier?: number;
    allowedKeys?: string[];
  };
}

Ejemplos Completos

Ejemplo 1: Crear Pico de Hierro

!item-crear iron_pickaxe

Base:

Nombre: Pico de Hierro
Descripción: Un pico resistente para minar minerales
Categoría: tools
Stackable: false,1

Props:

{
  "tool": { "type": "pickaxe", "tier": 2 },
  "breakable": { "enabled": true, "maxDurability": 150, "durabilityPerUse": 1 }
}

Ejemplo 2: Crear Área de Mina

!area-crear mine.iron_cavern

Base:

Nombre: Caverna de Hierro
Tipo: MINE

Config:

{ "cooldownSeconds": 60 }

Ejemplo 3: Crear Nivel de Mina

!area-nivel mine.iron_cavern 1

Requisitos:

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

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 }
  ]
}

Mobs:

{
  "draws": 1,
  "table": [
    { "mobKey": "cave_spider", "weight": 10 },
    { "mobKey": "bat", "weight": 5 }
  ]
}

Permisos Requeridos

Todos los comandos de creación/edición requieren:

Permiso ManageGuild en Discord, O
Rol de staff configurado en el servidor (verificado en hasManageGuildOrStaff)

12 KiB Raw Blame History

Documentación del Sistema de Economía y Minijuegos

Índice

Items (EconomyItem)

Crear Items

Editor Interactivo

Modal "Base"

Modal "Tags"

Modal "Props (JSON)"

Editar Items

Tipos de Props Disponibles

1. tool (Herramientas)

2. breakable (Rompible/Durabilidad)

3. chest (Cofres)

4. food (Comida/Pociones)

5. Stats de Combate

Mobs (Enemigos)

Crear Mobs

Editor Interactivo

Modal "Base"

Modal "Stats (JSON)"

Modal "Drops (JSON)"

Editar Mobs

Áreas de Juego (GameArea)

Crear Áreas

Editor Interactivo

Modal "Base"

Modal "Config (JSON)"

Modal "Meta (JSON)"

Editar Áreas

Niveles de Área (GameAreaLevel)

Crear/Editar Niveles

Editor Interactivo

Modal "Requisitos (JSON)"

Modal "Recompensas (JSON)"

Modal "Mobs (JSON)"

Modal "Ventana"

Ofertas de Tienda (ShopOffer)

Crear Ofertas

Editor Interactivo

Modal "Base"

Modal "Precio (JSON)"

Modal "Ventana"

Modal "Límites"

Editar Ofertas

Servicios del Sistema

Economy Service

Funciones Principales:

Minigames Service

Funciones Principales:

Equipment Service

Funciones Principales:

Tipos de Datos Importantes

ItemProps (src/game/economy/types.ts:74-96)

Price (src/game/economy/types.ts:10-14)

LevelRequirements (src/game/minigames/types.ts:11-15)

Ejemplos Completos

Ejemplo 1: Crear Pico de Hierro

Ejemplo 2: Crear Área de Mina

Ejemplo 3: Crear Nivel de Mina

Permisos Requeridos

12 KiB

Raw Blame History