Reference

Configuration

Every block of config.yml and every line of messages.yml, with their defaults.

config.yml and messages.yml are written from a schema: comments are regenerated on every start, unknown keys are dropped, and a key you delete comes back with its default. The catalogue is emotes.yml — see Emotes — and the screens are in menus/.

`behaviour`

When an emote may play, and what calls one off.

behaviour:
  require-permission: true
  hide-without-permission: false
  cooldown: 3s
  cancel-on-move: true
  move-tolerance: 0.6
  cancel-on-damage: true
  block-in-combat: true
  endless-limit: 5m
  worlds: []

Key	Default	What it does
`require-permission`	`true`	Whether performing an emote needs owning it. Only `/emotesadmin play` reaches past it.
`hide-without-permission`	`false`	Whether an emote the player does not own is hidden in the menu instead of shown locked.
`cooldown`	`3s`	How long before the same player may play any other emote. Written out: `3s`, `1m30s`. `0s` turns it off.
`cancel-on-move`	`true`	Whether walking ends an emote.
`move-tolerance`	`0.6`	How far a player may drift before `cancel-on-move` fires, in blocks. Never less than `0.05`: a client sends tiny corrections while standing still.
`cancel-on-damage`	`true`	Whether being hit ends an emote, including another player punching the body.
`block-in-combat`	`true`	Whether an emote is refused while the player is combat tagged, by whichever combat plugin ExyliaLib is bridged to.
`endless-limit`	`5m`	The longest an endless emote runs before it ends by itself. Never less than a second.
`worlds`	`[]`	The worlds emotes may be played in, ignoring case. Empty means every world.

Leave cancel-on-damage on

A player performing an emote is frozen and cannot see who is next to them. The emote does not protect them, so the least it can do is get out of the way when it starts hurting.

cancel-on-move governs the movement the server sees and the walking keys it hears as its own input event. A walking key read straight off the connection ends an emote whatever it says — see Playing an emote.

`camera`

camera:
  enabled: true
  hide-body: true

Key	Default	What it does
`enabled`	`true`	Whether the player is shown their own emote from outside. Off, every `[CAMERA]` line is removed as the catalogue is compiled: the emote still plays for everybody around them, they simply do not see it.
`hide-body`	`true`	Whether the real player is hidden while their body plays. Off, the player and their body stand in the same place at once.

With the camera off a player can really walk, which is what move-tolerance is for. The startup log says so when the camera is off.

`duet`

duet:
  invite: 20s
  max-distance: 3.0

Key	Default	What it does
`invite`	`20s`	How long an invitation stands before it expires. Never less than a second.
`max-distance`	`3.0`	How far apart the two players may be, in blocks, both when inviting and when it starts.

The distance does not decide where the bodies stand: they are always placed on the line between the two players, the emote's own gap apart. See Duets.

menu:
  tab-open: "{success}✔ You are here"
  tab-closed: "{warning}➥ Click to open"
  favourites-name: "Favourites"
  favourites-icon: "AMETHYST_SHARD"
  favourite-on: "{highlight}★ In your favourites"
  favourite-off: "{muted}☆ Not in your favourites"
  kind-solo: "Solo"
  kind-duet: "With a friend"

Key	What it is
`tab-open` / `tab-closed`	`%category_status%` on the tab being looked at, and on the others.
`favourites-name` / `favourites-icon`	What the favourites tab is called and drawn as.
`favourite-on` / `favourite-off`	`%emote_favourite%` for a starred and an unstarred emote.
`kind-solo` / `kind-duet`	`%emote_kind%` for a one-player and a two-player emote.

The screen itself is menus/emotes.yml — see The menu.

`tiers`

The rarities emotes are sorted into, and how often each one comes out of a crate. Add, rename or delete any of them — the key is the id emotes.yml writes as tier. Full reference on The crate.

tiers:
  common: { name: "Common", material: GRAY_DYE, color: "{muted}", chance: 60.0, priority: 1 }
  rare: { name: "Rare", material: LIGHT_BLUE_DYE, color: "{info}", chance: 25.0, priority: 2 }
  epic: { name: "Epic", material: PINK_DYE, color: "{accent}", chance: 12.0, priority: 3 }
  legendary: { name: "Legendary", material: ORANGE_DYE, color: "{highlight}", chance: 3.0, priority: 4 }

chance is a weight, not a percentage.

`crate`

crate:
  enabled: true
  start-keys: 1
  duplicate-refund: 1
  reward: UNLOCK
  blocks: []
  max-at-once: 4
  spin-frames: 34
  stagger-seconds: 2.0
  on-spin:
    sound:
      name: BLOCK_NOTE_BLOCK_HAT
      pitch: 1.6
  on-win:
    sound:
      name: ENTITY_PLAYER_LEVELUP
      pitch: 1.2
  on-duplicate:
    sound:
      name: BLOCK_NOTE_BLOCK_BASS
      pitch: 0.8

Key	Default	What it does
`enabled`	`true`	Off, the crate says so instead of opening.
`start-keys`	`1`	Keys a player is given the first time they are seen.
`duplicate-refund`	`1`	Keys handed back for an emote already unlocked.
`reward`	`UNLOCK`	`UNLOCK`, `ITEM` or `BOTH`. An emote has no item, so all three unlock it.
`blocks`	`[]`	The blocks that open the crate, as `server,world,x,y,z,yaw,pitch`. Bind them with `/emotesadmin crate block add`.
`max-at-once`	`4`	How many crates one player may open in one go, up to seven.
`spin-frames`	`34`	How many faces the first reel runs through. Capped at 200, about eleven seconds.
`stagger-seconds`	`2.0`	How long after one reel stops the next one does. `0` stops them together.
`on-spin`	A hat note	Played on every tick a reel is still falling.
`on-win`	A level-up	Played the moment a reel stops on something new, once per crate.
`on-duplicate`	A bass note	Played instead when that reel stopped on something already unlocked.

`key-item`

How a crate key that can be held is drawn.

key-item:
  material: TRIPWIRE_HOOK
  name: "{primary}&lEMOTE KEY"
  lore:
    - "{secondary}Information:"
    - " {letters_black}▎ {letters}Right click the crate holding this"
    - " {letters_black}▎ {letters}to {highlight}open it {letters}once."
    - ""
    - "{secondary}Note:"
    - " {letters_black}▎ {letters}This one can be traded and dropped."
    - ""
    - "{warning}➥ Right click the crate to open"
    - ""
  glow: true

A key is recognised by what it carries in its data, so renaming or recolouring it changes nothing for the keys already out there.

`preview`

Where an emote can be watched without performing it: /emote preview, and right click in the menu.

preview:
  location: ""
  distance: 5.0
  settle-ticks: 4
  linger-ticks: 20
  max-ticks: 600

Key	Default	What it does
`location`	Empty	Where the player stands while a preview plays. Set it with `/emotesadmin preview location`. Only the position is used: a preview always faces north.
`distance`	`5.0`	How far in front of the player the emote plays, in blocks. Never less than `1`.
`settle-ticks`	`4`	How long to wait after the teleport before playing. Reads a written duration too: `1s`, `500ms`.
`linger-ticks`	`20`	How long the stage is held after the emote ends.
`max-ticks`	`600`	The longest a preview may last, whatever happens.

Empty means no stage, and previews answer preview-unavailable. Two players previewing at once may share it: everyone is hidden from everyone, and each emote is sent to one player.

`showcase`

showcase:
  locations: []
  pause-seconds: 3.0
  radius: 24.0
  emotes: []

Key	Default	What it does
`locations`	`[]`	Where emotes play on a loop. Set them with `/emotesadmin showcase add`.
`pause-seconds`	`3.0`	The rest between one emote ending and the next starting.
`radius`	`24.0`	How close a player has to be for a showcase to play and to see it, in blocks.
`emotes`	`[]`	The ids a showcase picks from. Empty picks from every one. Duets are never picked.

See Showcases.

`feedback`

feedback:
  on-play:
    sound:
      name: BLOCK_AMETHYST_BLOCK_CHIME
      pitch: 1.4
  on-cancel:
    sound:
      name: BLOCK_GRINDSTONE_USE
      pitch: 0.9
  on-invite:
    sound:
      name: BLOCK_NOTE_BLOCK_BELL
      pitch: 1.6

Key	Played
`on-play`	To the player the moment their emote starts — to both, in a duet.
`on-cancel`	To the performers when an emote is ended before its time. Not when it runs to the end.
`on-invite`	To whoever is invited into a duet.

These and the three crate blocks are full ExyliaLib effect blocks: title, action bar, boss bar, sound, particle and firework are all available on each. Every shipped one is a single sound at volume 1.0, in the PLAYERS category.

`placeholders`

placeholders:
  none: "None"
  unknown: "Unknown"

Key	Returned by
`none`	A player placeholder asked with no player, and `playing_id` / `playing_name` when nothing is playing.
`unknown`	An `emote_<id>_<field>` placeholder naming an emote or a field that does not exist.

`messages.yml`

Every line the plugin sends. prefix is {primary}&lEMOTES &8•&r and every other message starts with %prefix%.

Key	Sent when	Placeholders
`playing`	An emote started.	`%emote%`, `%id%`, `%player%`
`unknown-emote`	The id names nothing, or the emote plays nothing.	`%emote%`, `%id%`
`no-permission`	The player does not own it.	`%emote%`, `%id%`
`on-cooldown`	A cooldown is running.	`%emote%`, `%time%`
`already-playing`	They are performing one.
`in-combat`	They are combat tagged.
`wrong-world`	Emotes are off in their world.
`needs-partner`	A duet was asked for with nobody named.	`%emote%`, `%id%`
`invite-sent`	To the inviter.	`%player%`, `%emote%`
`invite-received`	To the invited player, with Accept and Decline buttons.	`%player%`, `%emote%`
`invite-expired`	The invitation ran out, or the inviter left.
`invite-declined`	To the inviter, when it was declined.	`%player%`
`invite-none`	Accepting or declining with nothing waiting.
`invite-self`	Inviting yourself.
`partner-too-far`	The partner is too far, or in another world.	`%player%`
`partner-busy`	The partner is performing something, or left.	`%player%`
`partner-cannot`	The partner cannot perform it, for any reason.	`%player%`
`list-header` / `list-entry` / `list-empty`	`/emote list`.	`%id%`, `%emote%`
`favourite-added` / `favourite-removed`	Starring and unstarring.	`%emote%`
`favourites-cleared` / `favourites-empty`	Emptying the shortlist, or finding it already empty.
`crate-won` / `crate-duplicate`	A reel landed on something new, or already unlocked.	`%emote%`, `%tier%`, `%refund%`
`crate-no-keys`	Not enough keys.	`%amount%`, `%keys%`
`crate-busy` / `crate-empty` / `crate-disabled`	The crate refused to open.
`given-key`	To a player handed key items.	`%amount%`
`rewards-claimed`	On join, when key items were waiting for them.	`%amount%`
`keys-received` / `keys-taken`	To a player whose account keys changed.	`%amount%`
`keys-given`	To the admin, after any `keys` subcommand.	`%player%`, `%amount%`
`unlock-granted` / `unlock-already` / `unlock-revoked` / `unlocks-cleared`	`unlocks` subcommands.	`%emote%`, `%player%`
`crate-block-added` / `crate-block-removed`	A block was bound or unbound.	`%location%`
`crate-block-already` / `crate-block-missing`	It already was, or never was.
`crate-block-none`	No block within six blocks is being looked at.
`crate-blocks-header` / `crate-blocks-entry` / `crate-blocks-empty`	`crate block list`.	`%location%`
`crate-blocks-cleared`	`crate block clear`.	`%amount%`
`preview-location-set`	The preview stage was moved.	`%location%`
`preview-unavailable` / `preview-unavailable-admin`	A preview was asked for before a stage was set; the second only to admins.
`showcase-added` / `showcase-removed`	A showcase was placed or removed.	`%location%`
`showcase-missing`	No showcase within five blocks.
`showcases-header` / `showcases-entry` / `showcases-empty`	`showcase list`.	`%location%`
`showcases-cleared`	`showcase clear`.	`%amount%`

Three keys are never sent

cancelled, camera-unavailable and refreshed are in the file but nothing sends them: an emote cut short says so with the on-cancel sound, and /emotesadmin reload reports through ExyliaLib's own reload line.

Every refusal of an emote fills %emote%, %id%, %player% and %time% whether or not the line uses them, so any of them can be added to any refusal line.

Something missing on this page? Tell us on Discord