Secuencias
Efectos coreografiados escritos en configuración: cada token, cada forma, los planos de cámara y los parámetros que mueven un display.
Una secuencia es coreografía escrita como una lista de textos — un anillo de fuego, un sonido, una pausa, una explosión, en ese orden. Se compila una vez y se lanza muchas.
PluginSequences sequences = Sequences.of(this);
Sequence onKill = sequences.compile(config.getStringList("effects"), "ember_burst");
sequences.play(onKill, SequenceTarget.at(victim.getLocation()).by(killer));effects:
- '[CIRCLE] FLAME;radius:1.5;points:24'
- '[SOUND] ENTITY_BLAZE_DEATH;1.5;0.8'
- '[DELAY] 0.15'
- '[EXPLOSION]'¿Secuencias o efectos?#
| Lo que tienes | Usa |
|---|---|
| Un título, un sonido, una partícula, declarados en un record | Effects |
| Una lista de cosas en orden, con pausas, formas y objetos | esto |
El sonido de apertura de un menú es un EffectConfig. Un espectáculo de cien líneas es una
Sequence.
La sintaxis#
Cada línea es un token entre corchetes, una cabecera y parámetros separados por ;:
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:3;points:12;from:0,10,0;ease:in'(0,0,0) es el ancla donde se lanzó la secuencia. La Y positiva es arriba.
Tokens#
| Token | Argumentos |
|---|---|
[DELAY] 0.15 | Segundos de espera antes de la línea siguiente, o escritos: 1m30s. |
[PARTICLE] FLAME | count: offset:x,y,z speed: y: color: fade: size: block: — fade: es el color al que se funde un DUST_COLOR_TRANSITION (blanco si falta). |
[SOUND] NOMBRE;volumen;tono | También volume: pitch:. Sirve la clave propia de un resource pack. |
[LIGHTNING] | volume: pitch: — destello, chispas y trueno. Sin rayo real, sin fuego, sin daño. |
[EXPLOSION] | count: y: |
[FIREWORK] | color: fade: type: trail: flicker: power: — con PacketEvents es una explosión por paquetes que solo ven los observadores de la secuencia; sin él, un cohete real que no hace daño. |
[BLOCK_BREAK] STONE | count: offset: y: |
[POTION] speed;100;1 | También duration: amplifier: particles: icon: ambient:. La duración son ticks (100 por defecto), o escrita: 5s. |
[TITLE] título;subtítulo;in;stay;out | Tiempos en segundos (0.5, 3.5, 1 por defecto), o escritos. who: como último segmento. |
[ACTION_BAR] texto | who: como último segmento. |
[MESSAGE] texto | Una línea de chat. <center> funciona como en cualquier otro sitio. who: como último segmento. |
[TOAST] icono;marco;texto | Un toast de logro — un ítem, TASK, GOAL o CHALLENGE, y el texto. who: como último segmento. Ver Avisos y toasts. |
[COMMAND] give {player} … | {player} {world} {x} {y} {z} |
[LID] open / [LID] close | Abre o cierra la tapa del cofre, cofre de ender o shulker del ancla, solo para los observadores. y: desplaza el bloque. |
[SHAKE] radius:10;times:2;every:0.08 | Inclina la cámara de los observadores a menos de radius bloques (10), como al recibir un golpe — sin daño ni sonido. times: (1) sacudidas, separadas every: (0,1 s). |
[CAMERA] keys:0 close | 2 yaw=~360 | Enseña al jugador su propia animación desde fuera — ver Planos de cámara. |
[DISPLAY] NETHERITE_SWORD | Un display — ver Displays y NPCs. |
[NPC] {victim} | Un cuerpo donde ocurrió — misma página. |
[RAGDOLL] {victim} | Ese cuerpo deshaciéndose en sus piezas — misma página. |
[FIREWORK], [EXPLOSION], [LIGHTNING], [SHAKE] y [CAMERA] no nombran nada en posición, así
que su primer segmento se lee como parámetro: [FIREWORK] color:red;fade:orange sale rojo.
Quién lee una línea de texto
[TITLE], [ACTION_BAR], [MESSAGE] y [TOAST] aceptan who: como último segmento ;, así
que un punto y coma dentro del texto sigue siendo texto:
who: | Se muestra a |
|---|---|
source (por defecto) | Quien lanzó la secuencia. |
target | A quien le pasó, cuando es un jugador. |
both | A los dos. |
nearby | Los observadores de la secuencia: su radio y su regla de visibilidad. |
all | Todos los jugadores conectados. |
- '[TITLE] {primary}JACKPOT;%reward%;0.2;3;0.5;who:nearby'Formas#
Veintiséis, y todas se pueden dibujar con partículas o con displays:
CIRCLE SPHERE DOME CUBE LINE RIBBON SCATTER BEAM SPIRAL DOUBLE_HELIX TORNADO
STAR CAGE DISC VORTEX WAVE CROSS GALAXY TORUS BURST PYRAMID RING_PULSE WINGS
ARCH CLAW PIXELS
| Forma | Sus parámetros |
|---|---|
CIRCLE, SPHERE, DOME | radius points |
BEAM | height points |
SPIRAL | height radius turns points |
DOUBLE_HELIX | height radius turns points strands |
TORNADO | height radius top_radius turns points |
STAR | radius spikes inner points |
CAGE | radius height columns points |
DISC | radius rings points |
VORTEX | radius turns points |
WAVE | length amplitude frequency arms angle points |
CROSS | radius arms angle points |
GALAXY | radius turns arms points |
TORUS | radius tube segments tube_segments |
BURST | radius beams angle points |
PYRAMID | base height points |
RING_PULSE | radius rings spacing points |
WINGS | span arch depth dir points |
ARCH | radius arc dir points |
CLAW | radius claws spread curve dir drop points |
CUBE | width points edges |
LINE | length dir climb points |
RIBBON | radius points waves amplitude |
SCATTER | radius height points seed floor |
PIXELS | art word pixel pick depth |
CUBE dice width y LINE dice climb en vez de size y rise, porque en una línea de displays
esas dos palabras ya significan la escala del modelo y dónde termina.
PIXELS dibuja una imagen — heart heart_big broken_heart star crown skull bolt note
cloud trophy ufo moon guillotine blade grave portal eye clock rift flag — o
una palabra (word) en una fuente de bloques de cinco filas, una pieza por celda. pick: elige qué
caracteres dibuja una línea, así que un corazón con brillo son dos líneas sobre una misma imagen.
Toda forma acepta además y: scale: color: size: count: ticks: interval: rotate:
face:. ticks:1 dibuja la forma entera en un fotograma; más alto la dibuja a lo largo del tiempo,
que es lo que hace que una espiral parezca trazada y no soltada. face:true gira la forma con quien la
lanzó. SCATTER acepta una seed, así que sus puntos sin plan son los mismos puntos sin plan cada vez.
Una forma dibuja como mucho max-per-effect puntos (128 por defecto, en
plugins/ExyliaLib/displays.yml). Un anillo escrito con points:900 se corta ahí y la consola lo
dice al leer el archivo, no como lag más tarde.
color:{primary} sigue colors.yml como todo lo que lee un jugador. #rrggbb y R,G,B también
funcionan. Una partícula DUST sin color se dibuja blanca — visible y obviamente mal, en vez de
invisible en silencio.
Dibujado con algo que no son partículas#
Cualquier línea de forma se convierte en una forma de displays diciendo de qué está hecha:
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:2.6;points:12;from:0,9,0;spin:2;axis:x;face_out:true'as: | La cabecera de la línea es |
|---|---|
item | Un nombre de ítem, NETHERITE_SWORD. |
block | Un nombre de bloque, o un estado completo como oak_stairs[facing=east]. |
head | Una textura base64, o {killer} / {victim} para una cara. |
text | La propia línea, con el formato de siempre. |
La geometría, la animación, la rotación y quién lo ve no cambian, porque una forma nunca supo con qué
se dibujaba. Los parámetros de movimiento — life, from, to, ease, gravity, spin, orbit,
pull, size_to, roll, glow, light, follow y el resto — están en
Displays y NPCs.
Repetir una línea a compás#
repeat: y every: funcionan en cualquier línea; una forma acepta además turn_each:.
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:3;points:6;repeat:5;every:0.1;turn_each:12'Cinco anillos separados una décima de segundo, cada uno doce grados más girado — en vez de cinco
copias de una línea con cuatro esperas entre ellas. every: vale 0,15 s si se omite.
Una línea repetida acepta también accel: y max_speed:: el hueco se divide por accel: tras cada
golpe y deja de acortarse en max_speed: veces la velocidad original. Así un sonido sigue el ritmo de
un cuerpo que acelera.
Un tempo por reproducción
Una línea [RAGDOLL] con tempo:1-1.6 hace toda la reproducción más rápida o más lenta con un número
sorteado una vez al empezar. El hueco de cada línea repetida se divide por ese mismo tempo, así que
los sonidos que marcan el compás de un baile siguen en él salga como salga el baile.
SequenceRun.tempo() lo devuelve.
Formas propias#
sequences.shape("heart", args -> {
List<Vector> points = new ArrayList<>();
double size = args.number("size", 1.0);
for (int i = 0; i < args.atLeastOne("points", 60); i++) {
double t = i / 60.0 * Math.PI * 2;
points.add(new Vector(size * Math.pow(Math.sin(t), 3),
size * (13 * Math.cos(t) - 5 * Math.cos(2 * t)) / 16, 0));
}
return points;
});Una forma dice dónde, nunca qué. Color, animación, rotación, escala, as: y visibilidad vienen
gratis, por eso una forma nueva es un bucle que devuelve vectores y no otra copia del código de dibujo.
Se llama una vez, al compilar.
Planos de cámara#
Un cuerpo que saluda o baila se dibuja para todos los que están alrededor del jugador y para nadie
dentro de él: el único jugador para quien se hizo está mirando desde sus ojos. [CAMERA] le enseña la
animación desde fuera.
effects:
- '[CAMERA] keys:0 close | 2.4 yaw=~360 ease=in_out | 0.4 behind ease=out'
- '[SOUND] ENTITY_PLAYER_LEVELUP;0.7;1.4'keys: va al final porque su valor está lleno de espacios y barras. Los fotogramas se separan con |;
cada uno empieza por los segundos que tarda en llegar y lista solo lo que cambia.
| Canal | Qué mueve |
|---|---|
distance= | A qué distancia está la cámara del sujeto, en bloques (0,6–24). |
yaw= | Dónde está a su alrededor: 0 a su espalda, 90 sobre su hombro izquierdo, 180 de frente. |
pitch= | Cuánto por encima del horizonte; positivo mira hacia abajo (±85). |
height= | A qué apunta, en bloques sobre sus pies. |
ease= | Cómo se llega al fotograma: in_out (por defecto), in, out, linear, back, anticipate, elastic, bounce, snap, smooth, hold. |
~90 suma a donde ya está el canal, así que yaw=~360 es una vuelta más a su alrededor. Una palabra
sola es un fotograma entero: behind, front, side, over, low, close, wide, top. smooth
traza una curva por los fotogramas vecinos en vez de pararse en cada uno. La cámara siempre mira al
sujeto; nada en un plano dice hacia dónde apunta.
| Parámetro | |
|---|---|
who: | De quién toma los ojos: source (por defecto), target o both. Nunca el público — una línea que tomara los ojos de todos los que están cerca de una kill no se podría escribir con seguridad. |
loop:true | Repite el recorrido al terminar — para un cuerpo que baila en bucle. El recorrido tiene que volver a donde empezó. |
El recorrido entero se resuelve al empezar, desde donde está el sujeto y hacia dónde mira, y las paredes acercan la cámara en vez de dejarla dentro de un bloque. Mientras dura, el jugador queda congelado y se le dibuja como espectador; ambas cosas se deshacen al final. Un plano dura como mucho 60 segundos y termina con la reproducción que lo lanzó, o cuando el jugador sale, muere o cambia de mundo. No es protección: al jugador se le puede seguir golpeando, así que un plugin que graba a alguien a la intemperie cancela la reproducción al recibir daño. Necesita PacketEvents.
En código, Cameras.of(this).play(player, CameraShot.parse(texto, problem -> …)) lanza el mismo plano
fuera de una secuencia.
Lanzado con SequenceTarget.of(player), un cuerpo dibujado sobre el jugador mira hacia donde él
miraba, así que el cuerpo y la cámara que lo graba coinciden.
Lanzar una#
SequenceRun run = sequences.play(sequence, SequenceTarget.at(location)
.by(killer)
.on(victim)
.within(20)
.visibleTo((observer, source) -> settings.seesEffects(observer)));
run.cancel();| En el objetivo | Qué fija |
|---|---|
at(location) / of(player) | El ancla. |
by(player) | Quién lo causó — lo que leen {killer}, face: y [COMMAND]. |
on(entity) | A quién le pasó — lo que lee {victim}. |
within(blocks) | Desde qué distancia se ve. 32 por defecto. |
onlyTo(player) | Un solo espectador, que es como se muestra una vista previa. |
visibleTo(predicate) | Quién puede percibirlo, preguntado una vez por fotograma. |
values(values) / item(name, stack) | Lo que rellena esta reproducción — ver abajo. |
durationMillis() dice cuánto dura una secuencia sin lanzarla, animación incluida. isEndless() es
cierto para una secuencia con un cuerpo o una cámara en bucle: dura hasta que se cancela su ejecución.
Valores que solo se conocen al lanzar#
Lo que tocó en una caja no se sabe al leer el archivo, así que lo lleva el objetivo:
sequences.play(reveal, SequenceTarget.at(crate.getLocation())
.by(opener)
.values(Values.of("reward", reward.displayName()).put("tier_color", "{highlight}"))
.item("reward", reward.icon()));- '[TITLE] {primary}&lHAS GANADO;%reward%;0.2;3;0.5'
- '[DISPLAY] {item:reward};from:0,0.5,0;to:0,1.6,0;life:3;ease:back_out;glow:%tier_color%'
- '[FIREWORK] color:%tier_color%;fade:#ffffff;type:star'%nombre% se rellena en el texto de [TITLE], [ACTION_BAR], [MESSAGE] y las líneas as:text, y
en color:, fade: y glow:. {item:nombre} como cabecera de una línea de ítem muestra el stack que
dio la reproducción; sin él la línea no dibuja nada. Todo lo demás se sigue compilando una vez.
Efectos que pueden sonar o no#
Una secuencia dice qué pasa. Un EffectEntry dice si pasa, a quién y cuándo:
EffectEntry crit = EffectEntry.of(List.of(
"[SOUND] ENTITY_PLAYER_ATTACK_CRIT;1;1.4",
"[PARTICLE] CRIT;count:20"))
.name("Critical hit")
.chance(25.0)
.condition("%player_level% >= 10")
.nearby(12.0)
.build();| Campo | Significa |
|---|---|
lines | Lo que se lanza. |
name, icon | Lo que muestra un editor. |
chance | El porcentaje de probabilidad de lanzarse. |
condition, permission | Para quién puede lanzarse. |
priority | Mayor va primero; las prioridades iguales mantienen su orden escrito. |
delayTicks | Cuánto después del disparador empieza esta entrada — las de al lado siguen a su hora. |
radius | 0 o menos es el jugador del que trata; un número es todos los que estén a esa distancia; EffectEntry.WHOLE_WORLD es el mundo entero. |
El permiso y la condición se evalúan antes de los dados: quién puede ver algo no depende de la suerte. Las entradas se compilan la primera vez que se lanzan y se cachean por sus propias líneas, y una condición rota se avisa una vez, no una por lanzamiento.
EffectCodec.encode / decode las guardan, y decode también lee filas de ExyliaCommons, traduciendo
su tipo a la línea que lanza lo mismo.
Editarlas en el juego#
sequences.editor(mine.breakEffects())
.title("{primary}&lBREAK EFFECTS")
.onSave(edited -> mines.save(mine, edited))
.open(player);Dos niveles de la pantalla de editor: las entradas y, dentro de una, sus líneas como su propia lista. Una línea se añade eligiendo qué lanza, buscando cuál en el registro del propio servidor y rellenando solo los campos que lee ese token — a un círculo se le pide el radio, a unas alas la envergadura. Los campos vacíos se omiten, así que una línea hecha con clics es la misma línea corta que alguien habría escrito a mano.
Las condiciones están tras el botón WHEN IT PLAYS, y las dos mitades se guardan o se descartan
juntas. Un token que la librería no reconoce se sigue dibujando, se puede editar como texto y vuelve
exactamente como se escribió.
Las líneas sueltas sin condiciones — las líneas de impacto de una habilidad de mob — abren la misma pantalla de líneas por sí solas:
sequences.editLines(player, "{primary}&lIMPACT LINES", skill.effect())
.thenAccept(edited -> edited.ifPresent(lines -> save(skill.withEffect(lines))));Contratos#
| Se compila una vez | Nombres, números y trigonometría se resuelven al compilar. Lanzar es aritmética y paquetes. |
| Una línea mala cuesta solo esa línea | Se avisa con Debug nombrando la secuencia; el resto se lanza. |
| Nunca toca el evento | Un efecto de kill no puede cancelar una muerte. |
| Correcto en Folia | Corre en el hilo dueño de la ubicación, a través de Tasks. |
| Las secuencias instantáneas no programan nada | Sin esperas ni animación se lanza en línea, en el mismo tick. |
| Cancelable | play devuelve un SequenceRun; cancel() para lo que aún no ha corrido, planos de cámara incluidos. |
| Una ejecución se suelta al terminar | Cuando corre su último fotograma se descarta, con sus cuerpos y displays. |
| Nada sobrevive a su plugin | Desactivar un plugin cancela sus ejecuciones antes de liberar el planificador. |
Un sonido renombrado se pasaba como una clave que no es clave: no sonaba nada y nada decía por qué. Ahora cuesta una línea de consola que nombra el efecto. Un nombre con un punto o dos puntos se deja tal cual, porque el sonido propio de un resource pack legítimamente no está en el registro.
Vistas previas#
PluginPreviews previews = Previews.of(this).using(() -> config.get().preview());
if (previews.available()) {
previews.show(player, sequence, () -> menu.open(player));
}Mueve al jugador a un escenario que construyó el dueño del servidor, lanza la secuencia delante de él
donde solo él la ve y lo devuelve exactamente a donde estaba — el callback corre acabe como acabe.
Mientras no haya escenario no hay vista previa: available() es false y show devuelve null sin
mover a nadie. Una secuencia sin fin se muestra seis segundos, unos cuantos ciclos, no para siempre.
PreviewSettings se anida en la config del propio plugin:
preview:
location: '' # server,world,x,y,z,yaw,pitch — vacío es sin vistas previas
distance: 5.0 # a qué distancia delante del jugador se lanza el efecto
settle-ticks: 4 # espera tras el teleport, para que el cliente tenga la posición
linger-ticks: 20 # cuánto se mantiene el escenario tras acabar el efecto
max-ticks: 600 # la red de seguridadCada plugin da a sus admins un comando setpreviewlocation para rellenar location. Solo se usa la
posición: una vista previa siempre mira al norte, así que cada efecto se ve desde el lado para el
que se dibujó — construye la sala con eso en mente y deja abierto el lado norte. Durante la vista
previa el jugador se sostiene volando, es invulnerable y está oculto para los demás; su modo de juego
nunca cambia.
sequences.preview(sequence, player) es la forma ligera: lo lanza solo para ese jugador, donde está,
sin escenario.
¿Falta algo en esta página? Dínoslo en Discord