Ragdolls

A body that comes apart, or moves like one. The player is cut into its six parts (head, torso, two arms, two legs), each wearing its own skin, and those parts move as one piece of choreography. The choreography can be thrown apart, opened out, spelled into letters or carried off, or it can be danced frame by frame.

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}'
  # A wave imported from Blockbench, with a body's lag and breath.
  - '[RAGDOLL] {victim};anim:wave;follow:1;breathe:1;rig:tophat'

Ragdolls need PacketEvents, like every display.

Who it wears

If no player can be worn, the line says so once and draws nothing. A plugin can hand the line a body of its own with SequenceTarget.wearing(model).

The poses

An unknown pose plays burst.

Its parameters

life: written always wins. Without it, a looping body lasts five minutes as a safety net, and a choreographed one lasts its intact time, its frames and its finish.

Choreography: keys:

keys: is a dance written frame by frame, frames split by |. Each frame starts with the seconds it takes to reach it, then a pose word or channels:

effects:
  - '[RAGDOLL] {victim};keys:0.25 crouch ease=anticipate | 0.35 stand up=1.6 flip=~-360 elbows=60 ease=out | 0.3 up=0 plant=1 knees=40 ease=bounce | 0.3 stand;then:dissolve;follow:1'

~ makes a value relative: flip=~-360 is one more backflip. The pose words are stand, tpose, star, cheer, reach, zombie, hug, crouch, sit, kneel, lie, prone, bow, pray, dab, superman, splits, float, limp, fetal, swoon, heart and arabesque; a pose word resets every bend. A turn faster than 160° a tick is warned about at load.

Bending, planting and breathing

• Bends. An elbow bends the forearm forward, a knee the shin back, the spine the chest forward. A direction of 90 bends outwards; -90 on an elbow bends it across the body. A body that bends is cut into at least two rows per limb, even at detail 1.
• Planted feet. At plant=1 the legs are solved to reach the floor, so a body that sinks bends its knees. The feet stay where they were when plant last rose from zero.
• Breathing. breathe: (0 to 3) lays a slow breath over every frame: the spine, the shoulders and the head, one breath every 3.4 seconds, fitted so a loop holds a whole number of them.
• Follow-through. follow: (0 to 3) makes loose joints lag and overshoot: 0 is exact, 1 a body, 2 a cartoon.

The finish: then:

What happens after the last frame: hold (the default), burst, collapse, implode, dissolve or spell.

Loops and wind-ups

A camera that goes round with a looping body is its own [CAMERA] line in the sequence.

Importing Blockbench and Emotecraft animations

plugins/<YourPlugin>/animations/wave.json

Put the file in the animations folder of the plugin whose sequence plays it. Files are read on first use and again whenever the folder changes; there is nothing to reload.

A single-animation file is named by its file name (wave.json → wave). An Emotecraft file also answers to its name, and each animation in a Blockbench file to its full key (animation.player.wave) or its last part (wave). Names ignore case. A file that loops sets loop and loop_from for you.

Props: rigs.yml

plugins/ExyliaLib/rigs.yml holds things made of blocks that a body wears, holds or carries. It is the server's file, not a plugin's, so every [RAGDOLL] line on the server can use every prop: rig:tophat, rig:crown,wand. It ships with tophat, crown, wand and cake.

rigs:
  halo:
    joint: head
    at: 0, 0.25, 0
    blocks:
      - 'ring GOLD_BLOCK r:0.30 n:18 y:0 s:0.08'

Numbers are in the joint's own axes: y runs along the limb and z is the way the body faces. A prop is solved with the body, so it stays in the hand through a cartwheel. 256 blocks at most per prop.

Real skins: ragdoll-skin-quality

A ragdoll wears the player's real skin with nothing to set up: no key, no account. The head is the player's real head item, so the face is exact from the first frame. The rest of the body is cut into pieces, and each piece is made into a texture by Exylia Skins, a free service with a cache shared by every server. A piece any server already made arrives at once; a new one is drawn in blocks of the nearest colour until it arrives. The only setting is how finely the body is cut, in plugins/ExyliaLib/config.yml:

ragdoll-skin-quality: normal

Once any of its pieces has arrived, a body in its real skin is cut by this quality and ignores detail:.

• Made once, for everybody. A piece is named by the hash of its pixels and uploaded once, ever. A piece that is one block's colour all over is drawn as that block and never uploaded. Each plugin that shows bodies keeps the pieces it got in its own database (table exylia_ragdoll_skins), so a restart asks for nothing.
• Prepared on join. A skin is prepared when its owner joins. A skin changed mid-session (such as SkinsRestorer's /skin) is prepared again the next time it is read.
• Offline mode. A player with no skin wears the default skin the game gives their UUID (Steve, Alex and the other default skins, wide or slim).
• Never a wait. A piece whose texture has not arrived yet is drawn in blocks until it does.
• Applied live. /exylialib reload reads the quality, and a change prepares the skins of everybody online again.

The API

PluginRagdolls ragdolls = Ragdolls.of(this);
 
RagdollAnimation hop = RagdollAnimation.parse(
        "0.25 crouch ease=anticipate | 0.35 stand up=1.6 flip=~-360 | 0.3 up=0 plant=1 knees=40 ease=bounce",
        problem -> getLogger().warning(problem));
 
RagdollMotion dance = RagdollMotion.builder()
        .pose(RagdollPose.ANIMATE)
        .animation(hop)
        .finish(RagdollFinish.DISSOLVE)
        .follow(1).breathe(1)
        .tempo(1.0, 1.3)
        .build();
 
RagdollProp crown = Rigs.get("crown");
RagdollModel body = RagdollModel.of(victim).detail(2).light(15)
        .rigs(crown == null ? List.of() : List.of(crown));
 
RagdollHandle handle = ragdolls.show(body, dance, victim.getLocation(), viewers);

ragdolls.show solves the whole flight before it returns. Nothing is simulated and nothing is ticked: every pose is worked out in advance and handed to the client.