Guía YAML events/

Crear eventos

Los eventos se definen como archivos .yml dentro de la carpeta plugins/EventUI/events/. Cada archivo puede contener un evento con sus objetivos, recompensas y metadatos.

Estructura de un evento

Este es un evento completo con todos los campos disponibles. Los marcados como obligatorios deben estar siempre presentes.

events/mi-evento.yml — estructura completa

# ── CAMPOS OBLIGATORIOS ──────────────────────────────────────
id: "mi-evento"               # Identificador único del evento
display_name: "Mi Evento"     # Nombre visible en la UI
description: "Descripción."   # Descripción del evento

# ── METADATOS (opcionales) ────────────────────────────────────
metadata:
  icon: "minecraft:diamond"   # Ítem usado como ícono en la UI
  difficulty: "medium"        # easy | medium | hard (solo visual)
  category: "combate"         # Categoría libre (solo visual)
  repeatable: "false"         # "true" = se puede repetir al completar

# ── COMPORTAMIENTO ────────────────────────────────────────────
always_active: true           # true = se inicia automáticamente
                              # false = requiere /eventui start
                              # Si no se define, usa el valor global de config.yml

# ── DEPENDENCIAS (opcionales) ─────────────────────────────────
dependencies:
  - "evento-anterior"         # IDs de eventos que deben completarse antes

# ── OBJETIVOS (al menos uno) ──────────────────────────────────
objectives:
  - id: "obj-1"
    type: KILL_ENTITY
    description: "Mata zombies"
    target_amount: 10
    parameters:
      entity_type: "minecraft:zombie"

# ── RECOMPENSAS (opcionales) ──────────────────────────────────
rewards:
  xp: 500
  items:
    - "minecraft:diamond 3"
    - "minecraft:cooked_beef 16"

Campos raíz

Campo	Tipo	Obligatorio	Descripción
`id`	String	✅ Sí	Identificador único. Solo letras, números y guiones. Debe ser único entre todos los eventos.
`display_name`	String	✅ Sí	Nombre visible en la UI y en mensajes del chat. Acepta `§` para colores.
`description`	String	✅ Sí	Descripción mostrada en la pantalla de detalle del evento.
`objectives`	Lista	✅ Sí	Lista de objetivos que el jugador debe completar. Al menos uno requerido.
`metadata`	Mapa	No	Datos adicionales del evento: ícono, dificultad, categoría, repeatable.
`always_active`	Boolean	No	Si es `true`, el evento se inicia automáticamente. Si no se define, usa el valor global de `config.yml`.
`dependencies`	Lista de IDs	No	Eventos que deben estar completados antes de que este esté disponible.
`rewards`	Mapa	No	Recompensas entregadas al completar el evento: XP e ítems.

Campos de metadata

Campo	Ejemplo	Descripción
`icon`	`minecraft:diamond`	ResourceLocation del ítem usado como ícono en la UI. Si no se define, usa `minecraft:paper`.
`difficulty`	`easy`	Valor libre — solo visual. Sugeridos: `easy`, `medium`, `hard`, `expert`.
`category`	`combate`	Categoría libre — solo visual. Útil para organizar eventos en la UI.
`repeatable`	`"false"`	`"true"` para que el evento se pueda repetir una vez completado. Por defecto `"false"`. Nota: debe escribirse entre comillas.

Definición de objetivos

Cada objetivo dentro de objectives requiere estos campos:

Campo	Tipo	Obligatorio	Descripción
`id`	String	✅ Sí	Identificador único del objetivo dentro del evento.
`type`	Enum	✅ Sí	Tipo de objetivo. Ver la lista completa de tipos.
`description`	String	✅ Sí	Texto mostrado en el HUD y en los mensajes de progreso.
`target_amount`	Número	✅ Sí	Cantidad necesaria para completar el objetivo. Debe ser un número sin comillas.
`parameters`	Mapa	Varía	Parámetros específicos del tipo de objetivo (entity_type, block_id, item_id, etc.).
`optional`	Boolean	No	Si es `true`, el objetivo no es necesario para completar el evento.

target_amount debe ser un número sin comillas. Escribir target_amount: "10" causará un error YAML en la consola del servidor. La forma correcta es target_amount: 10.

Formato alternativo con target:

El parser también acepta el formato target: con subcampos, útil para objetivos donde el parámetro principal y el contador van juntos:

Formato con target: (equivalente)

objectives:
  - id: "minar-piedra"
    type: MINE_BLOCK
    description: "Mina bloques de piedra"
    # Formato A — recomendado
    target_amount: 10
    parameters:
      block_id: "minecraft:stone"

  - id: "minar-piedra-alt"
    type: MINE_BLOCK
    description: "Mina bloques de piedra"
    # Formato B — alternativo, equivalente al anterior
    target:
      count: 10
      block_id: "minecraft:stone"

Recompensas

El bloque rewards soporta XP e ítems. Ambos son opcionales y se pueden combinar:

Ejemplos de recompensas

# Solo XP
rewards:
  xp: 1000

# Solo ítems
rewards:
  items:
    - "minecraft:diamond 5"        # 5 diamantes
    - "minecraft:golden_apple 1"   # 1 manzana dorada
    - "minecraft:bread 32"         # 32 panes

# XP + ítems combinados
rewards:
  xp: 500
  items:
    - "minecraft:emerald 3"
    - "minecraft:experience_bottle 10"

El formato de cada ítem es "namespace:id cantidad". Si no se especifica cantidad, se entrega 1 unidad.

Ejemplos completos

Evento simple — un solo objetivo

events/matar-zombies.yml

id: "matar-zombies"
display_name: "§cCazador de no-muertos"
description: "Elimina zombies para ganar experiencia."

metadata:
  icon: "minecraft:rotten_flesh"
  difficulty: "easy"
  category: "combate"
  repeatable: "false"

always_active: true

objectives:
  - id: "kill-zombies"
    type: KILL_ENTITY
    description: "Mata zombies"
    target_amount: 25
    parameters:
      entity_type: "minecraft:zombie"

rewards:
  xp: 300
  items:
    - "minecraft:iron_sword 1"

Evento con múltiples objetivos

events/supervivencia-basica.yml

id: "supervivencia-basica"
display_name: "§eSupervivencia básica"
description: "Reúne los recursos esenciales para sobrevivir tu primera noche."

metadata:
  icon: "minecraft:crafting_table"
  difficulty: "easy"
  category: "tutorial"
  repeatable: "false"

always_active: true

objectives:
  - id: "minar-madera"
    type: MINE_BLOCK
    description: "Recolecta madera"
    target_amount: 16
    parameters:
      block_id: "minecraft:oak_log"

  - id: "craftear-pico"
    type: CRAFT_ITEM
    description: "Fabrica un pico de madera"
    target_amount: 1
    parameters:
      item_id: "minecraft:wooden_pickaxe"

  - id: "minar-piedra"
    type: MINE_BLOCK
    description: "Mina bloques de piedra"
    target_amount: 8
    parameters:
      block_id: "minecraft:stone"

  - id: "craftear-cama"
    type: CRAFT_ITEM
    description: "Fabrica una cama"
    target_amount: 1
    parameters:
      item_id: "minecraft:white_bed"
    optional: true   # No es obligatorio para completar el evento

rewards:
  xp: 150
  items:
    - "minecraft:cooked_beef 8"
    - "minecraft:torch 16"

Evento con dependencias

events/mineria-avanzada.yml

id: "mineria-avanzada"
display_name: "§6Minería avanzada"
description: "Desciende hasta el bedrock y encuentra diamantes."

metadata:
  icon: "minecraft:diamond_pickaxe"
  difficulty: "hard"
  category: "mineria"
  repeatable: "false"

# Este evento solo aparece si "supervivencia-basica" está completado
dependencies:
  - "supervivencia-basica"

objectives:
  - id: "alcanzar-nivel"
    type: REACH_LEVEL
    description: "Alcanza el nivel 10"
    target_amount: 10

  - id: "minar-diamantes"
    type: MINE_BLOCK
    description: "Extrae diamantes"
    target_amount: 5
    parameters:
      block_id: "minecraft:diamond_ore"

rewards:
  xp: 1000
  items:
    - "minecraft:diamond_pickaxe 1"

Organización de archivos

El plugin carga archivos .yml de forma recursiva desde la carpeta events/. Puedes usar subcarpetas para organizar tus eventos sin ningún problema:

Estructura con subcarpetas

plugins/EventUI/events/
├── tutoriales/
│   ├── supervivencia-basica.yml
│   └── primera-noche.yml
├── combate/
│   ├── matar-zombies.yml
│   ├── matar-esqueletos.yml
│   └── boss/
│       └── derrotar-wither.yml
└── mineria/
    ├── mineria-basica.yml
    └── mineria-avanzada.yml

El nombre del archivo no importa — el plugin usa el campo id dentro del YAML para identificar cada evento. Dos archivos con el mismo id causarán que el segundo sobreescriba al primero.

Errores comunes en el YAML

Error en consola	Causa	Solución
Un campo numérico tiene comillas	`target_amount: "10"`	Quita las comillas: `target_amount: 10`
Un campo de texto necesita comillas	Descripción con caracteres especiales sin comillas	Envuelve el valor entre comillas: `description: "Mata 25: enemigos"`
Falta un campo obligatorio	Falta `id`, `type` o `description`	Verifica que todos los campos obligatorios estén presentes
Tipo de objetivo inválido	`type: kill_entity` (minúsculas)	El tipo debe estar en mayúsculas: `type: KILL_ENTITY`
Verifica la indentación	Uso de tabs en lugar de espacios	YAML solo acepta espacios. Usa 2 o 4 espacios por nivel de indentación

Si tienes dudas sobre la sintaxis de tu YAML, pégalo en yamllint.com para detectar errores antes de subirlo al servidor. El plugin también imprime en consola el archivo exacto que causó el problema.

Hot reload

No necesitas reiniciar el servidor para aplicar cambios en los archivos de eventos ni uis. Al hacer un cambio en cualquier archivo de UI y guardarlo, esta se recargará automaticamente despues de 2-3s.

Esto recarga todos los archivos de events/ y uis/, y notifica a los clientes conectados del cambio. El progreso de los jugadores no se pierde al hacer reload.