MermodSync

MermodSync lets players with the Mermod client mod see and use the sea necklace on your server, even though your server itself is 100% vanilla Paper. No Mixin, no Forge / NeoForge / Fabric loader, no hybrid server hacks — just the vanilla Synchronize Tags packet.

How it works

Mermod detects the necklace by checking whether the item worn in the chest slot belongs to the #mermod:sea_necklace item tag. MermodSync registers that tag on the server side, pointing it at a special Heart of the Sea variant — an item that's normally impossible to wear as chest armor in vanilla, made wearable only for the specific stacks this plugin issues. That means regular items on your server are never accidentally mistaken for the necklace.

Features

• Zero client-server coupling — players without Mermod see a normal (if unusual) piece of jewelry; players with Mermod see the full tail effect.
• Server-authoritative swim boost — instead of relying on client-side prediction (which would desync/rubber-band without the mod on the server), MermodSync grants vanilla Dolphin's Grace while swimming, so movement stays perfectly in sync for everyone.
• Water Breathing & Night Vision while submerged with the necklace equipped, mirroring the mod's own effect behavior.
• /necklace give <player> [hex color] — hand out necklaces with custom dye colors on the fly.
• Instant config reload — edit config.yml and changes apply immediately, no restart needed.
• Folia-ready — all scheduling goes through the correct region/entity schedulers.

Requirements

• Paper (or a Paper fork such as Purpur) 1.21.3+
• Players who want to see the tail effect need the Mermod mod installed client-side — this plugin only handles server-side detection and effects, it doesn't add rendering (that's the mod's job).

Known limitations

Mermod's cosmetic modifiers (tail style, bra, color gradient, glint, "permanent tail") are stored in a custom data component that only exists when the mod itself is loaded, so a vanilla server currently cannot set them. Base necklace detection, the swim boost, and the ambient effects all work today; full modifier support is pending upstream changes in Mermod to expose a vanilla-compatible fallback.

Credits

Huge thanks to ThatPreston, the developer of Mermod, for adding the #mermod:sea_necklace tag check that makes this whole project possible.