Objetos especiales

Cada objeto especial — una habilidad de combate, una herramienta o las dos cosas — es un archivo en plugins/ExyliaSpecials/lang/<idioma>/items/. Los archivos se leen en orden alfabético al arrancar y con /specialsadmin reload; la consola termina con Loaded N special items.

id: freeze                    # opcional; el nombre del archivo si falta
settings:                     # valores con nombre, usados abajo como ${nombre}
  cooldown: {value: 30, min: 1, max: 600, name: 'Cooldown (seconds)'}
  radius: {value: 5, min: 1, max: 16, name: 'Radius (blocks)'}
texts:                        # líneas para los jugadores, usadas como ${text.<clave>}
  no_target: '%prefix% {error}Nobody is close enough to freeze.'
item:                         # cómo se ve el objeto
  material: ICE
  name: '{primary}&lFREEZE %limit_badge%'
  display-name: '{info}FREEZE'
  lore: [...]
permission: ''                # nodo opcional comprobado en cada uso
limit: {type: USES, amount: 3}
cooldown: {seconds: '${cooldown}'}
regions: {...}                # opcional, necesita WorldGuard
features:                     # qué hace el objeto
  - type: ability
    trigger: RIGHT_CLICK
    actions: [...]

Un objeto se salta, con un aviso en la consola que nombra el archivo, cuando no tiene sección item o ninguna feature se cargó. Una feature con un type desconocido o una clave rota se descarta con un aviso y el resto del objeto se carga igual. Dos archivos con el mismo id: se salta el segundo.

id

La identidad del objeto: como lo llaman los comandos, los cooldowns, los placeholders y la API, y lo que se escribe en cada copia que se reparte. Por defecto es el nombre del archivo sin .yml, y no distingue mayúsculas.

settings

Números con nombre que usa el resto del archivo. Existen para que el lore, el límite, el cooldown y las acciones lean todos el mismo valor, y para que el staff pueda cambiarlos desde un formulario dentro del juego.

settings:
  uses: 3                                                      # forma corta
  radius: {value: 5, min: 1, max: 16, name: 'Radius (blocks)'}  # forma completa

Los nombres de los ajustes son letras minúsculas, dígitos y _. Se usan en cualquier otra parte del archivo:

• ${radius} — se sustituye por el valor. Un valor entero escrito solo (amount: '${uses}') se convierte en número.
• ${duration - 0.1}, ${every * 20}, ${percent / 100} — una fórmula sobre los ajustes, calculada al cargar.

Una referencia a un ajuste que no existe se deja tal cual y se registra en la consola.

El botón de ajustes de la pantalla de administración del objeto edita estos valores: abre un formulario, comprueba cada valor contra sus límites, escribe settings.<clave> en el archivo y recarga los objetos.

texts

Líneas que las features envían a los jugadores — un rechazo, el nombre de una invocación — reunidas en un sitio para que las traducciones puedan sustituirlas:

texts:
  no_target: '[sound:ENTITY_VILLAGER_NO|1.0|1.0]%prefix% {error}Nobody is close enough to freeze.'

Se usan en cualquier parte como ${text.no_target}. Un texto puede contener a su vez referencias ${ajuste}. Un [sound:NOMBRE|volumen|tono] al principio reproduce un sonido con el mensaje.

item

El objeto en sí, en el formato de objetos de ExyliaLib:

Placeholders del nombre y el lore

Los placeholders de PlaceholderAPI se rellenan para quien lleva el objeto. Las secciones de los contadores de estadísticas se añaden bajo el lore — ver Contadores.

El nombre y el lore de un objeto solo se reconstruyen cuando algo cambia en él — un uso, la cuenta de un contador, una edición del archivo — y cada segundo mientras un objeto temporal está en la mano principal.

permission

Un nodo comprobado en cada uso. Un jugador sin él recibe "No puedes usar este objeto." En blanco o sin poner: todos pueden usar el objeto. Ningún objeto incluido define uno. Una feature también puede tener su propio permission, que se comprueba después del del objeto.

limit

Un amount de 0 o menos, o un tipo desconocido, significa INFINITE. /specialsadmin give y la pantalla de administración del objeto pueden repartir una copia con otro límite.

Un objeto temporal se quita cuando se usa después de caducar ("Tu objeto ha caducado."), o en menos de un segundo si está en la mano principal. Un objeto caducado guardado en cualquier otro sitio sigue ahí hasta que se coge o se usa.

cooldown

cooldown:
  seconds: 30
  combat-seconds: 45     # opcional: se usa en su lugar mientras el jugador está en combate

El tiempo hasta que el objeto se puede volver a usar, que empieza cuando una feature termina su trabajo. Una feature puede llevar su propio bloque cooldown:, que sustituye a este para esa feature. Cada feature de un objeto lleva su propio temporizador, así que un objeto con una habilidad de clic derecho y otra de agacharse tiene dos cooldowns independientes.

El tiempo que empieza de verdad es, en orden: el cooldown de la feature, si no el del objeto; combat-seconds en su lugar cuando el jugador está en combate; y una entrada de regions.cooldowns para una región donde esté el jugador sustituye a cualquiera de los dos.

regions

Necesita WorldGuard; sin él todas estas reglas pasan.

regions:
  disable-in-non-pvp: true    # rechazado donde WorldGuard deniega el PvP
  mode: BLACKLIST             # NONE | WHITELIST | BLACKLIST
  list: [spawn, market]
  cooldowns:                  # id de región -> segundos
    arena: 5

Los rechazos dicen "No puedes usar este objeto en esta región."

Cuando una feature actúa sobre otro jugador — al golpearlo, o el jugador golpeado de un combo — la posición de ese jugador tiene que pasar las mismas reglas, y el PvP tiene que estar permitido tanto donde está quien lo usa como donde está el otro jugador. Esa comprobación es silenciosa.

features

La lista de lo que hace el objeto. Cada entrada tiene un type:

• ability — una cadena de pasos de acción, descrita abajo y en Lenguaje de acciones.
• Un tipo de herramienta — area_break, vein_miner, tree_capitator, auto_replant, till, seed_planter, bonemeal_area, crowbar, infinite_bucket, magnet, prospector, compressor, void_filter, telekinesis o auto_smelt. Ver Herramientas.

Claves que acepta cualquier feature:

ability

- type: ability
  trigger: HIT_PLAYER
  uses: 1
  combo: {hits: 3, window: 4}
  cooldown: {seconds: 18}
  actions:
    - action: damage
      damage: 3
      true-damage: true

trigger es obligatorio. cancel-event es true por defecto — un objeto de clic derecho no se come, no se lanza y no se coloca — salvo en CONSUME, PROJECTILE_LAUNCH, PROJECTILE_HIT y BOW_SHOOT, donde es false para que la comida se coma y la flecha salga.

Triggers

Cuando el objeto de la mano secundaria responde al mismo trigger que el de la mano principal, solo se ejecuta el de la mano principal.

Cómo se comprueba un uso

Cada uso pasa por las mismas comprobaciones en este orden. La primera que falla lo termina:

1. Silenciado — el jugador tiene el estado SILENCED: "Tus objetos especiales están silenciados."
2. Permiso — el del objeto y luego el de la feature: "No puedes usar este objeto."
3. Región — las reglas regions del objeto: "No puedes usar este objeto en esta región."
4. El otro jugador — sobre un jugador objetivo, su región y el PvP en las dos posiciones. Silencioso.
5. Combo — todavía no es el golpe N. Silencioso.
6. Cooldown — "Este objeto está en cooldown » 12s ⌚".
7. Caducado — el objeto se quita: "Tu objeto ha caducado."
8. Usos — no le quedan para esta feature: "A este objeto no le quedan usos."
9. SpecialItemUseEvent — otro plugin puede cancelarlo. Ver API.

Después se ejecuta la feature. Los triggers de golpe, TAKE_DAMAGE, HELD y CARRIED no envían ninguno de los mensajes de arriba: una comprobación que falla ahí es silenciosa.

Cobros y devoluciones

El cooldown empieza y el uso se gasta solo cuando la feature ha terminado su trabajo. Una habilidad cuya cadena llega a un stop, a un require que falla, o a un paso summon o duel que no pudo ocurrir no gasta nada. Una herramienta que no tenía nada que hacer — un minador de vetas sobre piedra, un prospector sin mineral alrededor — tampoco gasta nada.

Una habilidad con pasos retrasados se cobra al empezar; si se detiene más tarde, el cooldown se borra y el uso se devuelve.

De qué se protege a los objetos especiales

• Usados como ingrediente de crafteo: el resultado se vacía.
• Colocados como bloque: rechazado.
• Un huevo especial no eclosiona. Un tótem especial nunca salva a quien lo lleva; un tótem vanilla en la otra mano sí.
• Los objetos arrojadizos con límite de usos no se gastan al lanzarlos; en su lugar bajan sus usos.
• Los aldeanos aceptan un objeto especial en un intercambio solo cuando es idéntico al que pide el intercambio — mismo id, usos y cuentas de contadores. Los objetos temporales, nunca.
• Las copias renombradas se siguen reconociendo; los objetos que solo se le parecen, no.

Dar objetos

Los objetos se dan con /specialsadmin give item, los menús de administración o la API. Una entrega más grande que el max-stack-size del objeto se divide. Lo que no cabe espera en la cola de ExyliaLib y se entrega en la próxima conexión del jugador. Al jugador se le avisa en los dos casos: "Recibido 2x CONGELAR", o que el objeto le espera en su próxima conexión.