Recorridos

Un recorrido es un archivo, journeys/<id>.yml; el nombre del archivo es su id. Es una lista ordenada de pasos más las reglas de cuándo empieza, quién puede hacerlo y qué da terminarlo. Todo esto se puede editar en el juego con /journeyadmin (consulta El editor); el archivo es el mismo de una forma u otra.

name: '{primary}&lWELCOME'
icon: COMPASS
description: ['{letters}Your first minutes on the server.']
enabled: true
priority: 10            # el más alto empieza primero cuando varios se disparan a la vez
group: main             # un recorrido activo por grupo
repeatable: false
cooldown: 0s
skippable: true
triggers:
  - FIRST_JOIN
requirements:
  permission: ''
  condition: '%player_level% >= 5'
steps:
  - id: spawn
    title: '{highlight}Find the fountain'
    objective: { type: REACH, location: 'world,0,64,0', radius: 4 }
rewards:
  - { type: EXPERIENCE, value: '100' }
  - 'give %player_name% bread 8'
on-start: []
on-complete: ['[MESSAGE] {success}Welcome aboard!']

Claves

Disparadores

Un disparador se escribe con su nombre solo cuando no necesita nada más, o como sección.

triggers:
  - FIRST_JOIN
  - type: REGION_ENTER
    region: spawn
  - type: REGION_ENTER
    location: world,0,64,0
    radius: 6
  - type: NPC_CLICK
    npc: guide
  - type: JOURNEY_COMPLETE
    journey: tutorial
  - type: PERMISSION
    permission: rank.member
  - type: CUSTOM
    key: exylia:crates:open

Un disparador al que le falta su clave (un NPC_CLICK sin npc) se reporta y se omite; el resto del recorrido se carga.

Quién puede iniciarlo

Cuando salta un disparador, el recorrido solo empieza si pasan todas las reglas, en este orden:

requirements.condition es una comparación de placeholders como %player_level% >= 5. Falla cerrada: una condición que el plugin no puede leer se reporta al cargar el recorrido y nadie la cumple, y un placeholder que no se resuelve en un número nunca pasa una comparación numérica.

/journeyadmin start y TEST ON YOURSELF del editor ignoran todas las reglas salvo ya activo.

Un recorrido detenido (por un admin, por el límite de tiempo de un paso o desde la API) es como si nunca hubiera empezado, y sus disparadores pueden volver a iniciarlo.

Varios recorridos a la vez

Un jugador puede llevar varios recorridos a la vez, uno por grupo. Solo uno se sigue: aquel cuyo paso muestra la guía y describen los placeholders. Un recorrido recién iniciado pasa a ser el seguido; cuando termina, toma el relevo el seguido más recientemente de los demás. Los jugadores cambian con /journey track <id>, o pasan de uno a otro haciendo clic en la tarjeta del recorrido en /journey.

El progreso cuenta en todos los recorridos activos, seguidos o no.

Saltar

Con skippable: true, un jugador puede saltar el recorrido entero desde /journey o con /journey skip journey, tras confirmarlo; con skippable: false recibe un rechazo. Un recorrido saltado no da nada, queda registrado como saltado y nunca vuelve a empezar por un disparador. Un admin puede borrarlo con /journeyadmin reset.

Saltar pasos sueltos depende del skippable del propio paso (consulta Pasos). Saltar un paso también pide confirmación, y un paso que no se puede saltar responde con un rechazo. Un paso saltado no da nada y empieza el siguiente. Saltar el último paso completa el recorrido.

Una partida en la que se saltó cualquier paso no da las recompensas de finalización del recorrido, así que saltar no sirve para conseguirlas; las líneas de on-complete se ejecutan igual. /journeyadmin complete sigue pagando completo.

Recompensas

rewards son recompensas de ExyliaLib, que se dan al completar el recorrido, salvo que en esa partida se saltara algún paso (consulta Saltar). Cada entrada es una sección con un type (ITEM, ECONOMY, EXPERIENCE, COMMAND, MESSAGE, POTION...) o un texto suelto, que se ejecuta como comando de consola:

rewards:
  - type: EXPERIENCE
    value: '100'
  - type: ITEM
    itemSnapshot: TORCH
    minAmount: 8
    maxAmount: 8
  - 'give %player_name% bread 8'

Los pasos tienen sus propias rewards, que se dan al completar ese paso. El editor construye ambas listas con el editor de recompensas de ExyliaLib.

Líneas de efectos

on-start y on-complete, en el recorrido y en cada paso, son líneas de interacción de ExyliaLib: comandos de consola o del jugador (console:, player:), [ACTION] namespace:id, [TELEPORT] y cada token de secuencia ([MESSAGE], [SOUND], [TOAST], [PARTICLE], [FIREWORK], [DELAY]...).

on-start:
  - '[SOUND] BLOCK_NOTE_BLOCK_CHIME;1;1.4'
on-complete:
  - 'console: give %player_name% bread 4'
  - '[MESSAGE] {success}Welcome aboard, {highlight}%player_name%{success}!'

Pueden usar estos placeholders, además de cualquier placeholder del jugador:

Feedback

Además de las líneas propias de cada archivo, cada paso completado reproduce el feedback de config.yml: un sonido, un toast y una ráfaga corta de partículas; cada recorrido completado lanza una celebración de fuegos artificiales y un anillo de partículas y envía un bloque centrado JOURNEY COMPLETE. Consulta Configuración.

Un archivo con errores

Nada en un archivo de recorrido detiene el servidor. Un disparador, paso o recompensa incorrectos se reportan en la consola indicando el archivo y la ruta (steps[2].objective), y se omiten; un recorrido sin ningún paso no se carga. /journeyadmin reload dice cuántos problemas encontró, y el editor los muestra en el recorrido y marca los pasos rotos.