Guía YAML objectives v1.0.1

Guía YAML objectives v1.0.0

Objetivos

Cada evento puede tener uno o más objetivos que el jugador debe completar. Esta página documenta todos los tipos disponibles con sus parámetros exactos y su estado de implementación actual.

Los estados de cada tipo son: ✅ Implementado — funciona completamente. ⚠️ Parcial — el código existe pero tiene limitaciones conocidas. ❌ No implementado — definido en el sistema pero sin handler activo.

Resumen de tipos

Tipo	Descripción corta	Estado
`MINE_BLOCK`	Minar un bloque específico	✅ Implementado
`PLACE_BLOCK`	Colocar un bloque	✅ Implementado
`KILL_ENTITY`	Matar una entidad	✅ Implementado
`CRAFT_ITEM`	Fabricar un ítem	✅ Implementado
`SMELT_ITEM`	Fundir un ítem en horno	✅ Implementado
`CONSUME_ITEM`	Consumir un ítem	✅ Implementado
`DAMAGE_ENTITY`	Infligir daño a una entidad	✅ Implementado
`TAME_ENTITY`	Domesticar una entidad	✅ Implementado
`BREED_ENTITY`	Criar una entidad	✅ Implementado
`ENCHANT_ITEM`	Encantar un ítem	✅ Implementado
`BREAK_WITH_TOOL`	Romper bloque con herramienta específica	✅ Implementado
`INTERACT`	Interactuar con bloque o entidad	✅ Implementado
`REACH_LEVEL`	Alcanzar un nivel de XP	✅ Implementado
`UNLOCK_ADVANCEMENT`	Completar un avance	✅ Implementado
`VISIT_BIOME`	Visitar un bioma	✅ Implementado
`VISIT_STRUCTURE`	Visitar una estructura generada	✅ Implementado
`VISIT_DIMENSION`	Entrar a una dimensión	✅ Implementado
`REACH_LOCATION`	Llegar a unas coordenadas	✅ Implementado
`COLLECT_ITEM`	Tener ítems en el inventario	✅ Implementado
`BREW_POTION`	Preparar una poción	✅ Implementado
`CUSTOM`	Tipo personalizado vía API	❌ No implementado

Tipos implementados

MINE_BLOCK ✅ Implementado

Se activa cuando el jugador rompe un bloque. El parámetro block_id es el ResourceLocation del bloque.

Ejemplo

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

Parámetro	Obligatorio	Descripción
`block_id`	✅ Sí	ResourceLocation del bloque. Ejemplo: `minecraft:diamond_ore`, `minecraft:deepslate_diamond_ore`.
`target_amount`	✅ Sí	Cantidad de bloques a minar. Puede ir dentro o fuera de `parameters`.

PLACE_BLOCK ✅ Implementado

Se activa cuando el jugador coloca un bloque.

Ejemplo

- id: "colocar-madera"
  type: PLACE_BLOCK
  description: "Coloca bloques de madera de roble"
  parameters:
    block_id: "minecraft:oak_log"
    target_amount: 20

Parámetro	Obligatorio	Descripción
`block_id`	✅ Sí	ResourceLocation del bloque a colocar.
`target_amount`	✅ Sí	Cantidad de bloques a colocar.

KILL_ENTITY ✅ Implementado

Se activa cuando el jugador mata una entidad. Solo cuenta si el jugador es el asesino directo.

Ejemplo

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

Parámetro	Obligatorio	Descripción
`entity_type`	✅ Sí	ResourceLocation de la entidad. Ejemplo: `minecraft:zombie`, `minecraft:skeleton`, `minecraft:creeper`.
`target_amount`	✅ Sí	Cantidad de entidades a matar.

CRAFT_ITEM ✅ Implementado

Se activa cuando el jugador saca un ítem de la mesa de crafteo.

Ejemplo

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

Parámetro	Obligatorio	Descripción
`item_id`	✅ Sí	ResourceLocation del ítem crafteado.
`target_amount`	✅ Sí	Cantidad a fabricar.

SMELT_ITEM ✅ Implementado

Se activa cuando el jugador extrae un ítem fundido del horno. Cuenta la cantidad extraída de una vez.

Ejemplo

- id: "fundir-hierro"
  type: SMELT_ITEM
  description: "Funde lingotes de hierro"
  parameters:
    item_id: "minecraft:iron_ingot"
    target_amount: 32

Parámetro	Descripción
`item_id`	ResourceLocation del ítem resultante del horno.
`target_amount`	Cantidad total a fundir.

CONSUME_ITEM ✅ Implementado

Se activa cuando el jugador consume (come o bebe) un ítem.

Ejemplo

- id: "comer-manzanas"
  type: CONSUME_ITEM
  description: "Come manzanas doradas"
  parameters:
    item_id: "minecraft:golden_apple"
    target_amount: 3

Parámetro	Descripción
`item_id`	ResourceLocation del ítem a consumir.
`target_amount`	Cantidad a consumir.

DAMAGE_ENTITY ✅ Implementado

Acumula el daño total infligido a una entidad. El target_amount es la cantidad total de daño (en puntos de vida, donde 1 corazón = 2 puntos).

Ejemplo

- id: "dañar-creepers"
  type: DAMAGE_ENTITY
  description: "Inflige daño a creepers"
  parameters:
    entity_type: "minecraft:creeper"
    target_amount: 100

Parámetro	Descripción
`entity_type`	ResourceLocation de la entidad objetivo.
`target_amount`	Daño total a infligir en puntos de vida (2 puntos = 1 corazón).

TAME_ENTITY ✅ Implementado

Se activa cuando el jugador domestica exitosamente una entidad.

Ejemplo

- id: "domesticar-lobos"
  type: TAME_ENTITY
  description: "Domestica lobos"
  parameters:
    entity_type: "minecraft:wolf"
    target_amount: 3

Parámetro	Descripción
`entity_type`	ResourceLocation de la entidad domesticable.
`target_amount`	Cantidad a domesticar.

BREED_ENTITY ✅ Implementado

Se activa cuando el jugador cría dos entidades y nace una cría.

Ejemplo

- id: "criar-vacas"
  type: BREED_ENTITY
  description: "Cría vacas"
  parameters:
    entity_type: "minecraft:cow"
    target_amount: 5

Parámetro	Descripción
`entity_type`	ResourceLocation de la entidad a criar.
`target_amount`	Cantidad de crías a producir.

ENCHANT_ITEM ✅ Implementado

Se activa cuando el jugador encanta un ítem en la mesa de encantamientos. El parámetro item_type es opcional — si no se especifica, cualquier encantamiento cuenta.

Ejemplo — cualquier ítem

- id: "encantar-cualquiera"
  type: ENCHANT_ITEM
  description: "Encanta cualquier ítem"
  parameters:
    target_amount: 3

Ejemplo — ítem específico

- id: "encantar-espada"
  type: ENCHANT_ITEM
  description: "Encanta una espada de diamante"
  parameters:
    item_type: "minecraft:diamond_sword"
    target_amount: 1

Parámetro	Obligatorio	Descripción
`item_type`	No	ResourceLocation del ítem a encantar. Si se omite, cualquier encantamiento cuenta.
`target_amount`	✅ Sí	Cantidad de encantamientos a realizar.

BREAK_WITH_TOOL ✅ Implementado

Se activa cuando el jugador rompe un bloque con una herramienta específica. El parámetro block_id dentro de este tipo es opcional.

Ejemplo — herramienta sin bloque específico

- id: "usar-pico-diamante"
  type: BREAK_WITH_TOOL
  description: "Rompe bloques con pico de diamante"
  parameters:
    tool_type: "minecraft:diamond_pickaxe"
    target_amount: 50

Ejemplo — herramienta Y bloque específico

- id: "minar-obsidiana-con-diamante"
  type: BREAK_WITH_TOOL
  description: "Mina obsidiana con pico de diamante"
  parameters:
    tool_type: "minecraft:diamond_pickaxe"
    block_id: "minecraft:obsidian"
    target_amount: 10

Parámetro	Obligatorio	Descripción
`tool_type`	✅ Sí	ResourceLocation de la herramienta requerida en la mano principal.
`block_id`	No	ResourceLocation del bloque a romper. Si se omite, cualquier bloque cuenta.
`target_amount`	✅ Sí	Cantidad de bloques a romper.

INTERACT ✅ Implementado

Se activa cuando el jugador hace clic derecho sobre un bloque o una entidad. El target_type define si es un bloque o entidad.

Ejemplo — interactuar con bloque

- id: "usar-cofre"
  type: INTERACT
  description: "Abre cofres"
  parameters:
    target_type: "block"
    target_id: "minecraft:chest"
    target_amount: 5

Ejemplo — interactuar con entidad

- id: "hablar-aldeano"
  type: INTERACT
  description: "Habla con aldeanos"
  parameters:
    target_type: "entity"
    target_id: "minecraft:villager"
    target_amount: 3

Parámetro	Obligatorio	Descripción
`target_type`	✅ Sí	`"block"` o `"entity"`.
`target_id`	✅ Sí	ResourceLocation del bloque o entidad objetivo.
`target_amount`	✅ Sí	Número de interacciones.

REACH_LEVEL ✅ Implementado

Se completa cuando el jugador sube al nivel de XP indicado. No acumula progreso — se completa de golpe cuando el jugador alcanza o supera el nivel requerido.

Ejemplo

- id: "nivel-30"
  type: REACH_LEVEL
  description: "Alcanza el nivel 30"
  parameters:
    level: "30"
    target_amount: 1

Parámetro	Descripción
`level`	Nivel mínimo requerido (como string entre comillas).
`target_amount`	Siempre `1` — este objetivo es binario.

UNLOCK_ADVANCEMENT ✅ Implementado

Se activa cuando el jugador completa un avance específico de Minecraft.

Ejemplo

- id: "matar-dragon"
  type: UNLOCK_ADVANCEMENT
  description: "Derrota al Ender Dragon"
  parameters:
    advancement_id: "minecraft:end/kill_dragon"
    target_amount: 1

Parámetro	Descripción
`advancement_id`	ResourceLocation del avance. Formato: `namespace:categoria/nombre`.
`target_amount`	Siempre `1` — los avances son binarios.

VISIT_BIOME ✅ Implementado

Se activa cuando el jugador se mueve hacia un bioma específico. Se comprueba en cada movimiento de bloque.

Ejemplo

- id: "visitar-desierto"
  type: VISIT_BIOME
  description: "Visita un desierto"
  parameters:
    biome_id: "minecraft:desert"
    target_amount: 1

Parámetro	Descripción
`biome_id`	ResourceLocation del bioma. Ejemplo: `minecraft:desert`, `minecraft:jungle`, `minecraft:deep_dark`.
`target_amount`	Siempre `1` — se completa al pisar el bioma.

VISIT_STRUCTURE ✅ Implementado

Se activa cuando el jugador entra en el chunk de una estructura generada.

Ejemplo

- id: "visitar-fortaleza"
  type: VISIT_STRUCTURE
  description: "Encuentra una fortaleza"
  parameters:
    structure_id: "minecraft:stronghold"
    target_amount: 1

Parámetro	Descripción
`structure_id`	ResourceLocation de la estructura. Ejemplos: `minecraft:stronghold`, `minecraft:village`, `minecraft:nether_fortress`, `minecraft:end_city`.
`target_amount`	Siempre `1`.

VISIT_DIMENSION ✅ Implementado

Se activa cuando el jugador cambia de dimensión. Los valores válidos de dimension son fijos.

Ejemplo

- id: "ir-nether"
  type: VISIT_DIMENSION
  description: "Entra al Nether"
  parameters:
    dimension: "nether"
    target_amount: 1

Parámetro	Descripción
`dimension`	Valores válidos: `"overworld"`, `"nether"`, `"the_end"`.
`target_amount`	Siempre `1`.

REACH_LOCATION ✅ Implementado

Se activa cuando el jugador llega a unas coordenadas dentro de un radio configurable. El sistema comprueba la posición mediante un scheduler periódico. Compatible con múltiples mundos.

Ejemplo

- id: "llegar-spawn"
  type: REACH_LOCATION
  description: "Llega al spawn"
  parameters:
    x: "0"
    y: "64"
    z: "0"
    radius: "10"      # radio en bloques (default: 3)
    world: "world"    # nombre del mundo (opcional)
    target_amount: 1

Parámetro	Obligatorio	Descripción
`x`	✅ Sí	Coordenada X objetivo (como string).
`y`	✅ Sí	Coordenada Y objetivo.
`z`	✅ Sí	Coordenada Z objetivo.
`radius`	No	Radio de detección en bloques. Default: `"3"`.
`world`	No	Nombre del mundo. Si se omite, funciona en cualquier mundo.
`target_amount`	✅ Sí	Siempre `1`.

COLLECT_ITEM ✅ Implementado

Verifica ítems en el inventario del jugador. El sistema comprueba periódicamente el inventario y avanza el progreso según la diferencia respecto al último check — solo cuenta cuando el jugador gana ítems.

Ejemplo

- id: "acumular-diamantes"
  type: COLLECT_ITEM
  description: "Ten 10 diamantes en el inventario"
  parameters:
    item_id: "minecraft:diamond"
    target_amount: 10

Parámetro	Descripción
`item_id`	ResourceLocation del ítem a acumular.
`target_amount`	Cantidad mínima a tener en el inventario.

BREW_POTION ✅ Implementado

Se activa cuando una poción termina de prepararse en un soporte de pociones. El sistema detecta el ciclo completo de brewing — no hace falta que el jugador tenga el GUI abierto al terminar.

El parámetro potion_type usa la clave del PotionType de Bukkit, que sigue el formato minecraft:nombre (sin sufijo _potion). Ejemplo: "minecraft:healing" para Poción de Curación, "minecraft:strength" para Poción de Fuerza.

Ejemplo

- id: "preparar-pociones"
  type: BREW_POTION
  description: "Prepara pociones de curación"
  parameters:
    potion_type: "minecraft:healing"
    target_amount: 3

Parámetro	Obligatorio	Descripción
`potion_type`	✅ Sí	Clave del tipo de poción. Formato: minecraft:nombre. Ejemplos: minecraft:healing, minecraft:strength, minecraft:swiftness, minecraft:fire_resistance.
`target_amount`	✅ Sí	Cantidad de pociones a preparar.

Para obtener la lista completa de tipos de poción válidos para tu versión de Paper, usa el comando /ev debug potions en el servidor — muestra todos los PotionType disponibles con su clave exacta.

IMPORTANTE: El sistema detecta solo pociones preparadas en un soporte de pociones (BrewingStand). Las pociones obtenidas por otros medios (crafteo, loot, comandos) no cuentan.

Tipos no implementados

El siguiente tipo está declarado en el sistema pero no tiene un handler activo. Definirlo en un evento no causará errores — simplemente el objetivo nunca avanzará.

Tipo	Descripción
`CUSTOM`	Tipo personalizado para integración vía API externa. Sin handler en esta versión.

Notas generales

Formato de target_amount: el parser acepta el valor tanto dentro como fuera de parameters. Ambas formas son equivalentes:

Formas equivalentes de escribir target_amount

# Forma A — target_amount dentro de parameters
objectives:
  - id: "minar-diamantes"
    type: MINE_BLOCK
    description: "Mina diamantes"
    parameters:
      block_id: "minecraft:diamond_ore"
      target_amount: 5

# Forma B — target_amount fuera de parameters
objectives:
  - id: "minar-diamantes"
    type: MINE_BLOCK
    description: "Mina diamantes"
    target_amount: 5
    parameters:
      block_id: "minecraft:diamond_ore"

# Forma C — formato target: con subcampos
objectives:
  - id: "minar-diamantes"
    type: MINE_BLOCK
    description: "Mina diamantes"
    target:
      block: "minecraft:diamond_ore"
      count: 5

Objetivos opcionales: si añades optional: true a un objetivo, el evento puede completarse sin que ese objetivo esté terminado:

Objetivo opcional

- id: "objetivo-bonus"
  type: KILL_ENTITY
  description: "Mata un creeper (bonus)"
  optional: true
  parameters:
    entity_type: "minecraft:creeper"
    target_amount: 1

Guía YAML objectives v1.0.0

Cada evento puede tener uno o más objetivos que el jugador debe completar. Esta página documenta todos los tipos disponibles con sus parámetros exactos y su estado de implementación actual.

Resumen de tipos

Tipo	Descripción corta	Estado
`MINE_BLOCK`	Minar un bloque específico	✅ Implementado
`PLACE_BLOCK`	Colocar un bloque	✅ Implementado
`KILL_ENTITY`	Matar una entidad	✅ Implementado
`CRAFT_ITEM`	Fabricar un ítem	✅ Implementado
`SMELT_ITEM`	Fundir un ítem en horno	✅ Implementado
`CONSUME_ITEM`	Consumir un ítem	✅ Implementado
`DAMAGE_ENTITY`	Infligir daño a una entidad	✅ Implementado
`TAME_ENTITY`	Domesticar una entidad	✅ Implementado
`BREED_ENTITY`	Criar una entidad	✅ Implementado
`ENCHANT_ITEM`	Encantar un ítem	✅ Implementado
`BREAK_WITH_TOOL`	Romper bloque con herramienta específica	✅ Implementado
`INTERACT`	Interactuar con bloque o entidad	✅ Implementado
`REACH_LEVEL`	Alcanzar un nivel de XP	✅ Implementado
`UNLOCK_ADVANCEMENT`	Completar un avance	✅ Implementado
`VISIT_BIOME`	Visitar un bioma	✅ Implementado
`VISIT_STRUCTURE`	Visitar una estructura generada	✅ Implementado
`VISIT_DIMENSION`	Entrar a una dimensión	✅ Implementado
`REACH_LOCATION`	Llegar a unas coordenadas	⚠️ Parcial
`COLLECT_ITEM`	Tener ítems en el inventario	⚠️ Parcial
`BREW_POTION`	Preparar una poción	❌ No implementado
`CUSTOM`	Tipo personalizado vía API	❌ No implementado

Tipos con implementación parcial

REACH_LOCATION ⚠️ Parcial

El código existe y los parámetros están definidos, pero el scheduler que llama a la comprobación usa valores hardcodeados y puede no funcionar consistentemente. Úsalo con precaución.

Ejemplo

- id: "llegar-spawn"
  type: REACH_LOCATION
  description: "Llega al spawn"
  parameters:
    x: "0"
    y: "64"
    z: "0"
    radius: "10"      # radio en bloques (default: 3)
    world: "world"    # nombre del mundo (opcional)
    target_amount: 1

Parámetro	Obligatorio	Descripción
`x`	✅ Sí	Coordenada X objetivo (como string).
`y`	✅ Sí	Coordenada Y objetivo.
`z`	✅ Sí	Coordenada Z objetivo.
`radius`	No	Radio de detección en bloques. Default: `"3"`.
`world`	No	Nombre del mundo. Si se omite, funciona en cualquier mundo.
`target_amount`	✅ Sí	Siempre `1`.

COLLECT_ITEM ⚠️ Parcial

Verifica ítems en el inventario del jugador. La lógica cuenta los ítems del tipo especificado y avanza el progreso con la diferencia respecto al último check. Funciona correctamente tras los fixes de v1.0.0.

Ejemplo

- id: "acumular-diamantes"
  type: COLLECT_ITEM
  description: "Ten 10 diamantes en el inventario"
  parameters:
    item_id: "minecraft:diamond"
    target_amount: 10

Parámetro	Descripción
`item_id`	ResourceLocation del ítem a acumular.
`target_amount`	Cantidad mínima a tener en el inventario.

COLLECT_ITEM solo avanza cuando el jugador gana ítems. Si los tira o los usa, el progreso no retrocede — pero tampoco vuelve a avanzar hasta que tenga más del máximo ya registrado. No es apto para objetivos de tipo "recolecta y entrega".

Tipos no implementados

Los siguientes tipos están declarados en el sistema pero no tienen un handler activo. Definirlos en un evento no causará errores — simplemente el objetivo nunca avanzará.

Tipo	Descripción
`BREW_POTION`	Preparar pociones en el soporte de pociones. Sin handler implementado en esta versión.
`CUSTOM`	Tipo personalizado para integración vía API externa. Sin handler en esta versión.

Notas generales

Formato de target_amount: el parser acepta el valor tanto dentro como fuera de parameters. Ambas formas son equivalentes:

Formas equivalentes de escribir target_amount

# Forma A — target_amount dentro de parameters (tu ejemplo funcional)
objectives:
  - id: "minar-diamantes"
    type: MINE_BLOCK
    description: "Mina diamantes"
    parameters:
      block_id: "minecraft:diamond_ore"
      target_amount: 5

# Forma B — target_amount fuera de parameters
objectives:
  - id: "minar-diamantes"
    type: MINE_BLOCK
    description: "Mina diamantes"
    target_amount: 5
    parameters:
      block_id: "minecraft:diamond_ore"

# Forma C — formato target: con subcampos
objectives:
  - id: "minar-diamantes"
    type: MINE_BLOCK
    description: "Mina diamantes"
    target:
      block: "minecraft:diamond_ore"
      count: 5

Objetivos opcionales: si añades optional: true a un objetivo, el evento puede completarse sin que ese objetivo esté terminado:

Objetivo opcional

- id: "objetivo-bonus"
  type: KILL_ENTITY
  description: "Mata un creeper (bonus)"
  optional: true
  parameters:
    entity_type: "minecraft:creeper"
    target_amount: 1