Displays and NPCs

Three modules with the same shape: none of them creates a real entity, all three are drawn straight to a client, and all three own the lifetime of what they show.

All three need PacketEvents. Without it the module says so once and draws nothing.

Why the client animates it

A display is told a pose and how long it has to get there, and draws every frame in between at the viewer's own frame rate. A two-second animation is about six packets per viewer, and it stays smooth on a server running at fifteen ticks a second, because the smoothness never depended on the tick rate.

Moving something by re-sending its position every tick is a twenty-frames-a-second animation that gets worse under load — which is what a particle trail pretending to be an object looks like.

Drawing a display from a sequence

Any shape line becomes a display line by naming what it is drawn with:

effects:
  # Twelve swords that fall out of the sky in a ring, spinning as they come.
  - '[CIRCLE] NETHERITE_SWORD;as:item;radius:2.6;points:12;from:0,9,0;to:0,0,0;spin:2;axis:x;life:0.9;face_out:true;light:15'
  # The floor buckling: a ring of blocks, flattened, growing outwards.
  - '[CIRCLE] CRYING_OBSIDIAN;as:block;radius:0.3;points:20;size:0.1;size_to:1.4;to:0,0.2,0;life:0.5;light:15'
  # One item, thrown up, tumbling, falling back down.
  - '[DISPLAY] TRIDENT;from:0,0.5,0;to:0,4,0;gravity:14;spin:3;axis:z;life:1.4;size:1.5'

How it moves

orbit: is the movement a straight line cannot express and the one that separates a shape that appears from a shape that is alive. vary:0.4 gives the pieces sizes that differ by up to two fifths — a hash of each point's position, not a random number, so it is the same every play. spin:0.5,2,1 tumbles on three axes, because nothing thrown in the world spins about exactly one.

Making a movement land

light:15 is worth setting on nearly every effect: a display lit by the world is black at night, and an effect that disappears after sunset is an effect players report as broken.

The display API

PluginDisplays displays = Displays.of(this);
 
DisplayModel blade = DisplayModel.item(new ItemStack(Material.NETHERITE_SWORD))
        .glow(0xFF6B9D)
        .light(15);
 
DisplayMotion thrown = DisplayMotion.builder()
        .life(1200)
        .from(0, 7, 0).to(0, 0, 0)
        .spin(Rotation.Axis.Z, 3)
        .build();
 
displays.show(blade, thrown, where, observers);

NPCs

effects:
  # The victim, face down, wearing what they died in, for four seconds.
  - '[NPC] {victim};pose:lying;life:4;equip:true'
  # Standing, turned to face whoever did it, outlined.
  - '[NPC] {victim};pose:standing;life:3;glow:{error};face:true'

spin: is the one to reach for when a body should not settle: turn: is one turn spread over the movement and then finished, spin: never stops. A body caught in a vortex is spin:220, one hanging in the light is bob:0.3;spin:40, and one still swinging at whatever killed it is swing:0.5;hold:NETHERITE_SWORD. scale: is the client's own scale attribute, so the whole model grows — 0.4 is a doll and 2.5 is something the room is not big enough for; it needs a 1.20.5 client, and an older one sees a player-sized body.

PluginNpcs npcs = Npcs.of(this);
 
NpcHandle body = npcs.show(NpcModel.of(victim)
                .wearing(victim)
                .pose(NpcPose.LYING)
                .glow(0xA33B53),
        victim.getLocation(), 4000, observers);
 
body.lookAt(killer.getLocation());

A body reads better at about half vanilla gravity — a real one is heavier than the eye expects and slower than the number says. pose:lying is the pose a sleeping player is drawn in, which is the only way to put a body on the floor without a model of your own; pose:standing with face:true is a different effect entirely: somebody who has stopped, and is looking at you.

Ragdolls

A body that comes apart. The player is cut into its six parts — head, torso, two arms, two legs — each one wearing the colours of their own skin, and then those parts are moved as a single piece of choreography: thrown, opened out, spun, flattened, spelled into letters, or carried off whole.

effects:
  # Thrown apart. The pieces leave outwards, fall, bounce and rest.
  - '[RAGDOLL] {victim};intact:0.3;life:2.6;speed:4.2;up:6.4;spin:2.2;detail:2;light:15'
  # Lifted, opened out, and taken upwards. Nothing is left on the floor.
  - '[RAGDOLL] {victim};pose:vortex;rise:3.0;open:0.7;turns:1.8;life:3.0;detail:2;glow:{highlight}'

The head takes {victim}, {killer}, or a base64 texture, exactly as [NPC] does. If what died was not a player the line says so once and draws nothing.

The poses

Its parameters

PluginRagdolls ragdolls = Ragdolls.of(this);
 
ragdolls.show(RagdollModel.of(victim).detail(2).light(15),
        RagdollMotion.builder().pose(RagdollPose.VORTEX).rise(3.0).build(),
        victim.getLocation(), observers);

Real skins: mineskin-key

Out of the box a ragdoll's head wears the player's real face, but the rest of the body is drawn in blocks: each piece takes the block nearest in colour to that part of the skin. A dark outfit therefore reads as a black body made of blocks. To have the whole body wear the real skin, ExyliaLib needs a MineSkin API key, set in ExyliaLib's own plugins/ExyliaLib/config.yml:

mineskin-key: 'your-key'
ragdoll-skin-quality: normal

• Made once per skin. A skin is prepared when its owner joins, uploaded in the background, and kept in the database of the plugin that shows the bodies (its database.yml, table exylia_ragdoll_skins). That server, or a network sharing that database, never uploads it again.
• The free plan's limits. MineSkin's free plan allows 20 uploads a minute and 100 an hour. Past the hour, uploads wait for it to reset and the console says when they start again.
• Never a wait. A piece whose texture has not arrived yet is drawn in blocks until it does.
• Applied live. /exylialib reload reads both keys, and a changed key or quality prepares the skins of everybody online again.

What all three guarantee

The ceiling on what displays may cost

plugins/ExyliaLib/displays.yml holds two numbers for the whole server, because what a client can be sent is a fact about the server rather than about the plugin that happened to send it.

max-viewer-displays: 20000
max-per-effect: 128

The budget counts viewers because that is the number that reaches the network: two hundred displays in an empty corner are nothing, and the same two hundred with thirty players around them are six thousand entities on clients that also have a fight to render. /exylialib reload picks up an edit; no restart.

Region flags

WorldGuard flags the library registers, so a region can refuse effects without any plugin depending on WorldGuard:

They are registered from the library's own onLoad, because WorldGuard locks its registry the instant it enables. On a server without WorldGuard every flag allows, and an unregistered flag, a missing world or a refused registry all answer the same way: a gate that cannot be asked never withholds anything.