Getting started

Introduction

What ExyliaHitEffect is: 90 display-driven hit effects, worn by the player or bound to a weapon.

ExyliaHitEffect plays an effect on whoever was struck, on every blow. An effect is drawn with display entities — real items and blocks that fly, turn and settle, animated by each player's own client rather than by the server tick. Particles are used for atmosphere around something solid, never as the thing itself.

90 effects in six categories ship in effects.yml.

Built to a budget

A kill effect plays once and can afford to be a production. A hit effect plays on every blow of every fight on the server, so the budget is the design:

Rule	Why
Under six tenths of a second	An effect still playing when the next hit lands is two effects on top of each other.
Ten displays at the very most	Three players trading blows is thirty of them on screen at once.
Quiet — volume `0.4` to `0.9`	This is a sound a player hears a thousand times an evening, not once.
Small — about a block	The anchor is the victim's chest, not their feet. Anything larger reads as a kill effect that went off by mistake.

Every shipped effect is written to those numbers. Anything you add should be too.

Two ways to own an effect

Way	Whose it is	Which server it suits
The menu	The player's: they pick one in `/hiteffect` and it plays whatever they hit with.	Practice, PvP
A weapon	The weapon's: an effect token is dropped onto a weapon and travels with it through chests, trades and deaths.	Survival, economy

behaviour.mode decides which is read — player, weapon or both — and is covered in Modes and tokens.

The categories

Category	Icon	What is in it
`impact`	`NETHERITE_SWORD`	Steel, plate and shock.
`crimson`	`REDSTONE`	Blood, bone and the red end of a fight.
`ember`	`BLAZE_POWDER`	Sparks, scald and soot.
`sculk`	`SCULK_SHRIEKER`	The deep dark: shriek, echo and decay.
`prism`	`AMETHYST_SHARD`	Crystal, frost and light.
`goofy`	`SLIME_BALL`	Jokes. Rubber ducks, pies and a sad trumpet.

Fifteen effects each. The whole list is in Effects.

Arrows carry their own answer

An arrow outlives the state of the hand that fired it — a player switches to a sword while it is still in the air. So the effect is decided and stamped onto the arrow as it leaves the bow, and that is what plays when it lands. A projectile this plugin never saw launched still belongs to its shooter and falls back to whatever they are holding.

Which hits count

A hit only plays an effect when the victim's type is allowed — effects.all-mobs, or the effects.allowed-mobs list. Cancelled hits play nothing: a blow another plugin refused does not throw sparks.

Visibility is the observer's

Mode	What they see
`ALL`	Every effect, theirs and everybody else's.
`NONE`	None at all.
`SELF_ONLY`	Only their own hits.
`OTHERS_ONLY`	Only other people's.

What a weapon carries

Binding writes one value onto the weapon — exyliahiteffect:effect, the effect id. The lines a player reads under a bound weapon are drawn on the way to the client and are never written to the item, so a shop, a crate or any other plugin reading that weapon finds exactly what it had.

Requirements

Requirement	Detail
Server	Paper 1.21 or newer. Folia supported.
Required	`packetevents`
Recommended	`ExyliaLib` (a soft depend: the loader installs it)
Optional	`PlaceholderAPI`
Database	Always. The choice, the visibility and the favourites live in one table.

Installation

The jars, the files it writes and the table it creates.

First steps

From a clean server to a player with an effect on their hits.

Effects

The full catalogue and how effects.yml is written.

Modes and tokens

The token, the remover, and what each mode changes.

Something missing on this page? Tell us on Discord