Content generated with AI — it may contain mistakes.

ExyliaEmotes/Getting startedUpdated in v1.4.1

Installation

The jars, the files it writes, and the two tables it uses.

Page 2 of 214 min read

You end up with ExyliaEmotes running, its files written and a preview stage set.

Before you start#

A Paper 1.21.1+ (or Folia 1.21.4+) server and the packetevents jar. See Introduction.

Installing#

Drop in the jars

ExyliaEmotes.jar and packetevents into plugins/. packetevents is a hard dependency: the plugin does not load without it. ExyliaLib is a soft depend — the loader installs it on the first start if it is not there.

Start the server

It writes config.yml, emotes.yml, database.yml and the lang/ folders with the menus and messages in English, Spanish, Portuguese, French, Russian and Turkish, and creates its table.

Grant the permissions

Nothing is usable until players can open the menu and own at least one emote. See Permissions.

Set a preview stage

Right clicking an emote in the menu previews it, and a fresh install has nowhere to do that. Stand where previews should play and run /emotesadmin preview location.

Check that it works#

The console shows ExyliaEmotes enabled, and plugins/ExyliaEmotes/ now holds config.yml, emotes.yml and database.yml. /emote opens the menu.

Files#

FileContents
config.ymlThe language, behaviour, the camera, duets, the favourites icon, rarities, the crate, the key item's look, the preview stage, showcases, feedback and the shop.
lang/<code>/messages.ymlEvery line the plugin sends, the prefix, the menu wording, the key item's name and lore, and placeholder fallbacks.
lang/<code>/emotes.ymlThe five tabs and the 107 emotes, one catalogue per language. Hand-written, not schema-managed: your comments and your layout survive a reload.
lang/<code>/menus/emotes.ymlThe main screen: tabs, grid, templates and buttons.
lang/<code>/menus/crate.ymlThe crate's first screen: how many to open at once.
lang/<code>/menus/crate_open.ymlThe reels falling, one column per crate.
spatial/emotes.ymlWhere every piece of the 3D selector stands.
spatial/crate.ymlThe look of the 3D crate opening, written by ExyliaLib the first time it is needed.
spatial/spots.ymlThe 3D selectors placed with /emotesadmin spatial place, once there is one.
database.ymlWhere rows are stored.

Which lang/ folder is read is language in config.yml — see Configuration.

emotes.yml is yours, and it still gets new emotes

config.yml and messages.yml are written from a schema, so an unknown key is dropped and comments are regenerated. emotes.yml is not: it is read exactly as written. On every start and reload it is compared with the one in the jar — an emote an update adds is written into your file, and anything you changed or deleted is left alone.

The menu files follow the same rule. When a release has to change a menu's layout it raises menu-version at the top of the file; the file is then replaced and your previous one is kept beside it.

The tables#

emotes_players#

This plugin's own table, one row per player. Both tables are classified as @account data for ExyliaLib's /exylialib wipe and resetplayer: a season wipe or a plain player reset leaves favourites, keys and unlocks alone, and naming @account clears them — see ExyliaLib's commands.

ColumnWhat it holds
uuidThe player.
nameTheir last known name.
favouritesThe emotes they starred, comma-separated, in their own order.
unlockedWhat the plugin's old crate had unlocked. Read once, never written again.
crate_keysThe keys the plugin's old crate held. Read once, never written again.
created_at / updated_atWhen the row was made and last written.

A newcomer's row is only held in memory until something is written to it, such as their first favourite.

A starred id the catalogue no longer declares is kept in the column and dropped where it is drawn, so a typo in a reload does not empty anybody's shortlist.

exylia_crate_players#

Keys and unlocks live in ExyliaLib's crate table, one row per player per plugin. The first time a player is seen there, their row is seeded from emotes_players:

What emotes_players has for themWhat the crate row starts with
No row at allcrate.start-keys keys and nothing unlocked — a newcomer.
A rowIts crate_keys and its unlocked, as they are, even when both are empty.

So an update from a version that ran its own crate carries every key and every unlock across. The old columns are never written again, so a rollback finds them as they were. Key items already sitting in inventories keep opening the crate too.

Updating#

Replace the jar and restart. /emotesadmin reload re-reads config.yml, messages.yml, emotes.yml and the menus, rebuilds the crate and restarts the showcases without touching the rest of the server — it deliberately does not reload the library, which is what /exylialib reload is for.

Emotes need a recent ExyliaLib

ExyliaEmotes 1.4 needs ExyliaLib 1.461.0 or newer: the 3D selector, the 3D crate opening and running on Paper 1.21.1 all live there. The loader installs the newest release, so this only matters on a server that pins an older one.

Something missing on this page? Tell us on Discord