Aureum

Apariencia

Items - Documentación Técnica ​

Esta documentación está dirigida a desarrolladores. Para información sobre items dirigida a jugadores, ver Items. Los items también pueden ser costo de aprendizaje de hechizos en los maestros NPC — ver Hechizos.

Estructura de Datos de Item ​

Los Item siguen una estructura tipada en TypeScript (en shared) que define:

typescript
interface Item {
  id: string;
  name: string;
  rarity: ItemRarity;
  sellable: boolean;
  icon: string;              // Nombre del archivo del icono (32x32px)
  animation?: string;
  type?: string;             // Tipo de item (equipment, consumable, quest, material)
  subtype?: string;           // Subtipo del item (ej: para weapons: dagger, sword, staff, etc.)
  slot?: EquipmentSlot;       // HEAD, BODY, WEAPON, SHIELD, RING, BACK, BOOTS, AMULET
  unique?: boolean;            // Si es true, el item es único y no se puede apilar (por defecto false)
  maxStack?: number;           // Límite de unidades por stack (solo aplica si unique=false, por defecto 99)
  bodyId?: number;            // ID del sprite de body
  weaponId?: number;          // ID del sprite de weapon
  shieldId?: number;          // ID del sprite de shield
  helmId?: number;            // ID del sprite de casco (en /assets/head/headX.png)
  modifiers: ItemModifiers;  // Modificadores que aplica el item
  setId?: string;             // ID del set al que pertenece (opcional)
}

Tipos y Subtipos de Items ​

Tipos de Items ​

Los items pueden tener los siguientes tipos:

  • equipment: Items de equipamiento (armaduras, armas, accesorios)
  • consumable: Consumibles (pociones, comida, etc.)
  • quest: Items de misión
  • material: Materiales para crafting

Subtipos de Armas ​

Los items de tipo weapon pueden tener los siguientes subtipos:

  • dagger: Daga
  • axe: Hacha
  • mace: Maza
  • sword: Espada
  • staff: Báculo
  • wand: Varita
  • knuckles: Puños
  • bow: Arco
  • crossbow: Ballesta
  • throwable: Arma Arrojadiza

El subtipo se muestra en el panel de información del inventario cuando seleccionas un item.

Gráficos de Items ​

Configuración de Assets ​

Todas las imágenes se cargan usando ASSETS_BASE_URL desde shared/constants.ts:

  • Desarrollo: /assets (servido por Vite)
  • Producción: Configurar variable de entorno ASSETS_CDN_URL con la URL del bucket

Estructura de Carpetas ​

assets/
├── item/          # Iconos de items (32x32px, para inventario/UI)
├── body/          # Sprites de armaduras/cuerpos
├── weapon/        # Sprites de armas
├── shield/        # Sprites de escudos
└── head/          # Sprites de cascos (se dibujan encima de la cabeza)

Carga de Assets ​

typescript
import { getAssetUrl } from '@shared/constants';

// Cargar icono de item
const iconUrl = getAssetUrl('item/sword_iron.png');
// En desarrollo: '/assets/item/sword_iron.png'
// En producción: 'https://cdn.aureum.cc/assets/item/sword_iron.png'

// Si el gráfico no existe, usar placeholder
const iconUrl = getAssetUrl('item/missing.png') || '../assets/imgs/noicon.png';

Especificaciones Técnicas ​

Iconos de Items:

  • Formato: PNG con transparencia
  • Tamaño: 32x32 píxeles (fijo, obligatorio)
  • Estilo: Vista isométrica o frontal, consistente con el estilo del juego
  • Fondo: Transparente
  • Placeholder: Si no existe el gráfico, usar ../assets/imgs/noicon.png (temporal hasta que se suban al bucket)

Sprites de Equipamiento:

  • Formato: PNG con transparencia
  • Estructura: Spritesheets con frames para diferentes direcciones
  • Organización:
    • Bodies: Frames por dirección (UP, RIGHT, DOWN, LEFT) y estado (idle, walk)
    • Weapons: Frames por dirección
    • Shields: Frames por dirección
    • Helms: Frames por dirección (mismo sistema que heads)

Configuración de CDN/Bucket ​

Para configurar la URL del bucket en producción:

  1. Variable de entorno:

    bash
    ASSETS_CDN_URL=https://tu-bucket.s3.amazonaws.com/assets

  2. El código automáticamente usará:

    • Desarrollo: /assets (local)
    • Producción: La URL del bucket configurada

  3. Estructura del bucket debe coincidir:

    bucket/
└── assets/
    ├── item/      # Iconos 32x32px
    ├── body/
    ├── weapon/
    ├── shield/
    └── head/

Definiciones de Items ​

Los items están definidos en shared/data/items.ts como la fuente única de verdad. Los templates NO se almacenan en la base de datos (similar a los NPCs).

Los sets están definidos en shared/data/itemSets.ts y están disponibles tanto para el cliente como para el servidor.

Para más detalles sobre la arquitectura del sistema de items, modificadores y sets, ver Arquitectura del Sistema.

Sistema de Encantamientos ​

El sistema de encantamientos permite aplicar modificadores adicionales a los items. Cualquier item puede tener cualquier encantamiento, y los modificadores del encantamiento se suman con los modificadores base del item.

Estructura de Datos ​

Los encantamientos están definidos en shared/data/enchantments.ts:

typescript
interface EnchantmentDefinition {
  id: string;              // ID único del encantamiento (ej: 'enchant_hp_002')
  name: string;            // Nombre del encantamiento (ej: 'Encantamiento de Vida')
  description?: string;    // Descripción opcional del efecto
  modifiers: ItemModifiers; // Modificadores que aplica el encantamiento
}

Nota sobre ItemModifiers: La interfaz ItemModifiers incluye campos para modificadores tradicionales (hp, mana, damage, defense, etc.) y también campos adicionales para mecánicas avanzadas que requieren lógica adicional para funcionar completamente: lifeStealPhysical, lifeStealMagic, reflectPhysicalDamage, reflectMagicDamage, healingOutput, healingReceived, noWalkNoise, noSpellWords, noStaminaCostPhysical, y modificadores para invocaciones (summonHpBonus, summonAttackSpeedBonus, summonPhysicalDamageBonus, summonMagicDamageBonus). Ver la definición completa en shared/types/item.ts.

Almacenamiento en Base de Datos ​

Los encantamientos se almacenan en la tabla character_inventory:

sql
CREATE TABLE character_inventory (
    character_id VARCHAR(36) NOT NULL,
    slot_index TINYINT NOT NULL,
    item_id VARCHAR(36) NOT NULL,
    enchant_id VARCHAR(36) NULL,  -- ID del encantamiento (NULL si no tiene)
    quantity INT NOT NULL DEFAULT 1,
    PRIMARY KEY (character_id, slot_index)
);

Notas importantes:

  • El enchant_id se almacena por slot del inventario, no por item template
  • Un item con encantamiento y uno sin encantamiento son considerados diferentes para el stacking
  • Items idénticos (mismo item_id y mismo enchant_id) se apilan juntos
  • Items con encantamiento respetan el maxStack del template

Aplicación de Modificadores ​

Cuando un item equipado tiene un encantamiento, los modificadores se combinan así:

Modificadores Finales = Modificadores del Template + Modificadores del Encantamiento + Bonos de Set + Buffs Temporales

Orden de aplicación:

  1. Primero se aplican los modificadores FLAT (suma directa)
  2. Luego se aplican los modificadores PORCENTUALES (multiplicación sobre el valor ya modificado)

Ejemplo: Si tienes 1000 HP base, +100 HP flat y +25% HP porcentual:

  • Paso 1 (flat): 1000 + 100 = 1100 HP
  • Paso 2 (porcentual): 1100 * 1.25 = 1375 HP final

El sistema combina automáticamente los modificadores en GameRoom.loadPlayerEquipment() y en BaseEntity.calculateFinalAttributes():

typescript
// Obtener modificadores del template base
const itemTemplate = await inventoryService.getItemTemplate(itemId);

// Obtener modificadores del encantamiento
const enchantModifiers = getEnchantmentModifiers(enchantId);

// Combinar modificadores
const combinedModifiers = { ...itemTemplate.modifiers };
Object.keys(enchantModifiers).forEach((key) => {
  const typedKey = key as keyof ItemModifiers;
  const enchantValue = enchantModifiers[typedKey];
  if (enchantValue !== undefined) {
    const current = combinedModifiers[typedKey] ?? 0;
    combinedModifiers[typedKey] = (current + enchantValue) as never;
  }
});

IDs de Encantamientos Disponibles ​

Los encantamientos siguen el patrón de nomenclatura: enchant_[tipo]_[nivel]

Categorías disponibles:

Vida (HP) ​

  • enchant_hp_001 - Encantamiento de Vida Menor (+20 HP)
  • enchant_hp_002 - Encantamiento de Vida (+50 HP)
  • enchant_hp_003 - Encantamiento de Vida Mayor (+100 HP)
  • enchant_hp_004 - Encantamiento Maestro de Vida (+200 HP)

Mana - FLAT ✅ ​

  • enchant_mana_001 - Encantamiento de Mana Menor (+30 Mana)
  • enchant_mana_002 - Encantamiento de Mana (+70 Mana)
  • enchant_mana_003 - Encantamiento de Mana Mayor (+150 Mana)
  • enchant_mana_004 - Encantamiento Maestro de Mana (+300 Mana)

Mana - PORCENTUAL ✅ ​

  • enchant_mana_pct_001 - Encantamiento de Mana Porcentual Menor (+10% Mana)
  • enchant_mana_pct_002 - Encantamiento de Mana Porcentual (+20% Mana)
  • enchant_mana_pct_003 - Encantamiento de Mana Porcentual Mayor (+30% Mana)
  • enchant_mana_pct_004 - Encantamiento Maestro de Mana Porcentual (+50% Mana)

Daño - FLAT ✅ ​

  • enchant_damage_001 - Encantamiento de Daño Menor (+2-5 Daño)
  • enchant_damage_002 - Encantamiento de Daño (+5-10 Daño)
  • enchant_damage_003 - Encantamiento de Daño Mayor (+10-20 Daño)
  • enchant_damage_004 - Encantamiento Maestro de Daño (+20-40 Daño)

Daño - PORCENTUAL ✅ ​

  • enchant_damage_pct_001 - Encantamiento de Daño Porcentual Menor (+8% Daño)
  • enchant_damage_pct_002 - Encantamiento de Daño Porcentual (+15% Daño)
  • enchant_damage_pct_003 - Encantamiento de Daño Porcentual Mayor (+25% Daño)
  • enchant_damage_pct_004 - Encantamiento Maestro de Daño Porcentual (+40% Daño)

Defensa Física ​

  • enchant_def_phys_001 - Encantamiento de Defensa Física Menor (+5 Def)
  • enchant_def_phys_002 - Encantamiento de Defensa Física (+10 Def)
  • enchant_def_phys_003 - Encantamiento de Defensa Física Mayor (+20 Def)
  • enchant_def_phys_004 - Encantamiento Maestro de Defensa Física (+40 Def)

Defensa Mágica ​

  • enchant_def_magic_001 - Encantamiento de Defensa Mágica Menor (+5 Def)
  • enchant_def_magic_002 - Encantamiento de Defensa Mágica (+10 Def)
  • enchant_def_magic_003 - Encantamiento de Defensa Mágica Mayor (+20 Def)
  • enchant_def_magic_004 - Encantamiento Maestro de Defensa Mágica (+40 Def)

Velocidad de Movimiento - FLAT ✅ ​

  • enchant_speed_move_001 - Encantamiento de Velocidad de Movimiento Menor (+0.1)
  • enchant_speed_move_002 - Encantamiento de Velocidad de Movimiento (+0.2)
  • enchant_speed_move_003 - Encantamiento de Velocidad de Movimiento Mayor (+0.3)
  • enchant_speed_move_004 - Encantamiento Maestro de Velocidad de Movimiento (+0.5)

Velocidad de Movimiento - PORCENTUAL ✅ ​

  • enchant_speed_move_pct_001 - Encantamiento de Velocidad de Movimiento Porcentual Menor (+5%)
  • enchant_speed_move_pct_002 - Encantamiento de Velocidad de Movimiento Porcentual (+10%)
  • enchant_speed_move_pct_003 - Encantamiento de Velocidad de Movimiento Porcentual Mayor (+15%)
  • enchant_speed_move_pct_004 - Encantamiento Maestro de Velocidad de Movimiento Porcentual (+25%)

Velocidad de Ataque - FLAT ✅ ​

  • enchant_speed_attack_001 - Encantamiento de Velocidad de Ataque Menor (+0.1)
  • enchant_speed_attack_002 - Encantamiento de Velocidad de Ataque (+0.2)
  • enchant_speed_attack_003 - Encantamiento de Velocidad de Ataque Mayor (+0.3)
  • enchant_speed_attack_004 - Encantamiento Maestro de Velocidad de Ataque (+0.5)

Velocidad de Ataque - PORCENTUAL ✅ ​

  • enchant_speed_attack_pct_001 - Encantamiento de Velocidad de Ataque Porcentual Menor (+5%)
  • enchant_speed_attack_pct_002 - Encantamiento de Velocidad de Ataque Porcentual (+10%)
  • enchant_speed_attack_pct_003 - Encantamiento de Velocidad de Ataque Porcentual Mayor (+15%)
  • enchant_speed_attack_pct_004 - Encantamiento Maestro de Velocidad de Ataque Porcentual (+25%)

Probabilidad de Crítico - FLAT ✅ ​

  • enchant_crit_chance_001 - Encantamiento de Probabilidad de Crítico Menor (+5%)
  • enchant_crit_chance_002 - Encantamiento de Probabilidad de Crítico (+10%)
  • enchant_crit_chance_003 - Encantamiento de Probabilidad de Crítico Mayor (+15%)
  • enchant_crit_chance_004 - Encantamiento Maestro de Probabilidad de Crítico (+25%)

Probabilidad de Crítico - PORCENTUAL ✅ ​

  • enchant_crit_chance_pct_001 - Encantamiento de Probabilidad de Crítico Porcentual Menor (+3%)
  • enchant_crit_chance_pct_002 - Encantamiento de Probabilidad de Crítico Porcentual (+5%)
  • enchant_crit_chance_pct_003 - Encantamiento de Probabilidad de Crítico Porcentual Mayor (+8%)
  • enchant_crit_chance_pct_004 - Encantamiento Maestro de Probabilidad de Crítico Porcentual (+15%)

Multiplicador de Crítico ​

  • enchant_crit_mult_001 - Encantamiento de Multiplicador de Crítico Menor (+0.2)
  • enchant_crit_mult_002 - Encantamiento de Multiplicador de Crítico (+0.5)
  • enchant_crit_mult_003 - Encantamiento de Multiplicador de Crítico Mayor (+0.8)
  • enchant_crit_mult_004 - Encantamiento Maestro de Multiplicador de Crítico (+1.2)

Evasión ​

  • enchant_evasion_001 - Encantamiento de Evasión Menor (+3%)
  • enchant_evasion_002 - Encantamiento de Evasión (+5%)
  • enchant_evasion_003 - Encantamiento de Evasión Mayor (+8%)
  • enchant_evasion_004 - Encantamiento Maestro de Evasión (+15%)

Regeneración de Vida ​

  • enchant_regen_hp_001 - Encantamiento de Regeneración de Vida Menor (+0.2)
  • enchant_regen_hp_002 - Encantamiento de Regeneración de Vida (+0.5)
  • enchant_regen_hp_003 - Encantamiento de Regeneración de Vida Mayor (+0.8)
  • enchant_regen_hp_004 - Encantamiento Maestro de Regeneración de Vida (+1.5)

Regeneración de Mana ​

  • enchant_regen_mana_001 - Encantamiento de Regeneración de Mana Menor (+0.2)
  • enchant_regen_mana_002 - Encantamiento de Regeneración de Mana (+0.5)
  • enchant_regen_mana_003 - Encantamiento de Regeneración de Mana Mayor (+0.8)
  • enchant_regen_mana_004 - Encantamiento Maestro de Regeneración de Mana (+1.5)

Stamina - FLAT ✅ ​

  • enchant_stamina_001 - Encantamiento de Stamina Menor (+20 Stamina)
  • enchant_stamina_002 - Encantamiento de Stamina (+50 Stamina)
  • enchant_stamina_003 - Encantamiento de Stamina Mayor (+100 Stamina)
  • enchant_stamina_004 - Encantamiento Maestro de Stamina (+200 Stamina)

Stamina - PORCENTUAL ✅ ​

  • enchant_stamina_pct_001 - Encantamiento de Stamina Porcentual Menor (+10% Stamina)
  • enchant_stamina_pct_002 - Encantamiento de Stamina Porcentual (+20% Stamina)
  • enchant_stamina_pct_003 - Encantamiento de Stamina Porcentual Mayor (+30% Stamina)
  • enchant_stamina_pct_004 - Encantamiento Maestro de Stamina Porcentual (+50% Stamina)

Regeneración de Stamina ​

  • enchant_regen_stamina_001 - Encantamiento de Regeneración de Stamina Menor (+0.2)
  • enchant_regen_stamina_002 - Encantamiento de Regeneración de Stamina (+0.5)
  • enchant_regen_stamina_003 - Encantamiento de Regeneración de Stamina Mayor (+0.8)
  • enchant_regen_stamina_004 - Encantamiento Maestro de Regeneración de Stamina (+1.5)

Lista completa: Ver shared/data/ENCHANTMENTS_LIST.md para la lista completa con todos los detalles, incluyendo el estado de implementación de cada encantamiento (✅ Implementado, ⚠️ Parcialmente Implementado, ❌ No Implementado).

Nota importante:

  • Todos los encantamientos ahora tienen 4 niveles (001, 002, 003, 004). Los niveles 001-003 son los que se pueden conseguir normalmente, mientras que el nivel 004 (Maestro) es un nivel especial y más poderoso diseñado como recompensa especial.
  • Muchos encantamientos tienen dos variantes: FLAT (suma directa) y PORCENTUAL (multiplicación sobre el valor ya modificado). Los flat se aplican primero, luego los porcentuales.

Nuevos Tipos de Encantamientos (Lógica Pendiente) ​

Los siguientes encantamientos están registrados en el sistema pero requieren lógica adicional para funcionar completamente:

Robo de Vida (Life Steal):

  • enchant_lifesteal_phys_001 a 004 - Robo de vida por daño físico (3%, 5%, 8%, 15%)
  • enchant_lifesteal_magic_001 a 004 - Robo de vida por daño mágico (3%, 5%, 8%, 15%)

Reflejo de Daño:

  • enchant_reflect_phys_001 a 004 - Reflejar daño físico recibido (5%, 10%, 15%, 25%)
  • enchant_reflect_magic_001 a 004 - Reflejar daño mágico recibido (5%, 10%, 15%, 25%)

Curación:

  • enchant_healing_output_001 a 004 - Aumentar curación a terceros (10%, 20%, 30%, 50%)
  • enchant_healing_received_001 a 004 - Aumentar curación recibida (10%, 20%, 30%, 50%)

Flags Especiales (solo nivel 001 - efectos binarios):

  • enchant_silent_walk_001 - No emitir ruido al caminar
  • enchant_silent_cast_001 - No emitir palabras mágicas al castear
  • enchant_no_stamina_phys_001 - No consumir energía al atacar físicamente

Invocaciones:

  • enchant_summon_hp_001 a 004 - Bonus de HP para invocaciones (+30, +60, +120, +250)
  • enchant_summon_atkspeed_001 a 004 - Bonus de velocidad de ataque para invocaciones (+0.1, +0.2, +0.3, +0.5)
  • enchant_summon_physdmg_001 a 004 - Bonus de daño físico para invocaciones (+5, +10, +20, +40)
  • enchant_summon_magicdmg_001 a 004 - Bonus de daño mágico para invocaciones (+5, +10, +20, +40)

Estos encantamientos utilizan nuevos campos en ItemModifiers que fueron agregados para soportar estas mecánicas futuras. Cuando se implemente la lógica correspondiente (sistema de combate con life steal, reflejo de daño, sistema de curación, sistema de invocaciones, etc.), estos modificadores estarán listos para aplicarse automáticamente.

Uso en Base de Datos ​

Para asignar un encantamiento a un item en el inventario:

sql
-- Asignar encantamiento a un slot específico
UPDATE character_inventory 
SET enchant_id = 'enchant_hp_002' 
WHERE character_id = '...' AND slot_index = 0;

-- Remover encantamiento (dejar en NULL)
UPDATE character_inventory 
SET enchant_id = NULL 
WHERE character_id = '...' AND slot_index = 0;

Comportamiento del Sistema ​

  1. Al equipar un item con encantamiento:

    • El sistema obtiene el enchantId del slot del inventario
    • Combina los modificadores del template + encantamiento
    • Aplica los modificadores combinados al personaje

  2. Al desequipar:

    • Los modificadores se remueven automáticamente (tanto del template como del encantamiento)

  3. Items del piso:

    • Los items tirados al piso mantienen su enchantId
    • Al recoger un item del piso, su enchantId se preserva

  4. Stacking:

    • Items sin encantamiento (enchant_id = NULL) se apilan independientemente del encantamiento
    • Items con encantamiento solo se apilan con items del mismo enchant_id
    • Items con encantamiento respetan el maxStack del template

  5. Suma de modificadores:

    • Los modificadores de múltiples items equipados se suman
    • Los modificadores de encantamientos también se suman entre items
    • Los bonos de sets se suman a los modificadores de items y encantamientos
    • Los buffs temporales se suman sobre todo lo anterior

Implementación Técnica ​

Servidor (server/src/services/InventoryService.ts):

  • getEquippedItems() devuelve Map<slot, { itemId, enchantId }>
  • addItemStack() acepta enchantId como parámetro
  • El enchantId se normaliza (strings vacíos se tratan como NULL)

Servidor (server/src/rooms/GameRoom.ts):

  • loadPlayerEquipment() combina modificadores del template + encantamiento
  • Usa getEnchantmentModifiers() de shared/data/enchantments.ts

Compartido (shared/data/enchantments.ts):

  • Contiene todas las definiciones de encantamientos
  • getEnchantmentDefinition(enchantId) - Obtiene la definición completa
  • getEnchantmentModifiers(enchantId) - Obtiene solo los modificadores
  • getAllEnchantments() - Lista todos los encantamientos disponibles

Agregar Nuevos Encantamientos ​

Para agregar un nuevo encantamiento, edita shared/data/enchantments.ts:

typescript
export const ENCHANTMENTS: Record<string, EnchantmentDefinition> = {
  // ... encantamientos existentes ...
  
  enchant_nuevo_001: {
    id: 'enchant_nuevo_001',
    name: 'Nombre del Encantamiento',
    description: 'Descripción del efecto',
    modifiers: {
      hp: 30,
      mana: 20,
      // ... otros modificadores ...
    },
  },
};

El sistema detectará automáticamente el nuevo encantamiento y estará disponible para usar en la base de datos.

Wiki del jugador de Aureum.

Aureum — MMORPG 2D top-down.