Installation

EdenEffects has two parts: a plugin for every Paper backend, and a small relay plugin for the Velocity proxy. Both are needed for cosmetics to sync between servers.

Requirements

Requirement	Detail
Backend software	Paper (built against Paper 26.2, api-version: 1.21)
Proxy software	Velocity 3.4
Java	25
Database	MySQL, shared by every backend
Soft dependency	LuckPerms, needed for temporary unlocks that expire on their own
Paper Dialog API	Needed for the pet editor and the "Save current look" dialog. Paper builds without it still run, with those two dialogs disabled.

StoneLib is shaded into both jars, so you do not install it separately. The MySQL driver is not shaded: it is listed under libraries in plugin.yml, so Paper downloads mysql-connector-j once on first start and shares it with any other plugin that asks for it.

Where each jar goes

Jar	Goes on
EdenEffects-1.0.0.jar	every Paper backend that should show cosmetics
EdenEffects-Velocity-1.0.0.jar	the Velocity proxy

---

Install steps

1. Create a database and user for EdenEffects on your MySQL server. The tables are created and migrated automatically on first start, so an empty database is all it needs.

   CREATE DATABASE edeneffects CHARACTER SET utf8mb4;
   CREATE USER 'edeneffects'@'%' IDENTIFIED BY 'change-me';
   GRANT ALL PRIVILEGES ON edeneffects.* TO 'edeneffects'@'%';

2. Put the Velocity jar in the proxy's plugins/ folder and restart the proxy. It needs no configuration. On start it logs Eden Effects relay listening on edeneffects:sync.

3. Put the Paper jar in each backend's plugins/ folder and start the server once. It creates plugins/EdenEffects/config.yml, then disables itself because server-id is empty. That is expected.

4. Edit config.yml on each backend:

   • Set server-id to the name Velocity knows that server by (the key under [servers] in velocity.toml). It must be unique across the network.
   • Fill in the database block so it points at the shared database.

5. Restart each backend. You should see:

   [EdenEffects] Connected to ...
   [EdenEffects] Registered 100 cosmetics

   The count depends on your server version, since almost every mob is offered as a pet.

6. Grant cosmetic permissions to your ranks. Ops have everything by default, and everyone else has nothing until you grant nodes. See Permissions.

server-id is required

The plugin refuses to start without server-id. The proxy uses it to route change messages and to skip the server a change came from. Two backends with the same server-id will miss each other's changes.

After first start the plugin folder holds a single file:

plugins/
└── EdenEffects/
    └── config.yml

Everything else (selections, pet settings, presets) lives in MySQL.

---

Quick test

1. Join a backend as an op and run /cosmetics.
2. Open Trails and click Flame. It goes on straight away and the menu stays open.
3. Close the menu and walk around. The trail follows you.
4. Switch to another backend through the proxy. The flame trail should still be there.

If the trail does not follow you, see Changes don't reach other servers.

---

Updating

On start, EdenEffects merges any new keys from the bundled config.yml into your existing file, so upgrading does not need a fresh config. Keys that were renamed or removed are handled through config-version. Database migrations run automatically.

Upgrading to config version 2

Join and death effects are now cosmetics players choose rather than something everyone gets. effects.join and effects.death no longer do anything, and nobody sees an effect until you grant the new edeneffects.join.*, edeneffects.leave.*, and edeneffects.death.* nodes. See Configuration.

---

Building from source

EdenEffects is a multi-module Maven project.

Setting	Value
Parent artifact	edeneffects-parent
Modules	plugin (Paper), velocity (proxy)
Java	25
Paper API	26.2.build.123-stable
Velocity API	3.4.0-SNAPSHOT
StoneLib	1.4

Paper's current release ships Java 25 class files, so building needs JDK 25. An older JDK cannot read paper-api at all.

mvn clean package

The jars are written to plugin/target/EdenEffects-1.0.0.jar and velocity/target/EdenEffects-Velocity-1.0.0.jar. StoneLib, BoostedYAML, and HikariCP are shaded and relocated under dev.anchorlight.edeneffects.libs, so they never clash with other plugins' copies.