Event Catalog

Events define when XenoLevels awards EXP. Each expression listens for a gameplay action, validates optional filters, and grants the amount you specify in exp-events.yml.

Expression syntax

Expressions follow EVENT[count]:ARG=value. Use :: or && for logical AND, || for logical OR, and ! to negate a condition.
[count] determines how many hits must accumulate before the section pays EXP. The effect depends on the count policy.
Arguments accept comma-separated lists or ranges where noted. Some events reject arguments entirely (policy NO_ARGS).
Set exp to a single number or a min, max range. Combine with partial-excessive for policy EXCESSIVE events to pay out leftover progress.

Tip

Commands, GUI buttons, and other plugins can trigger events through placeholders or command hooks. Combine them with conditions and anti-abuse rules for maximum control.

Count policies

Policy	Behavior
NORMAL	Pays EXP whenever the expression meets `[count]`. Omit `[count]` to treat each trigger as one hit.
EXCESSIVE	Tracks stack-like events (smelting batches, dropped items). With `partial-excessive: true`, leftover hits pay a proportional amount.
IGNORED	Ignores `[count]` entirely and fires once per event occurrence.
NO_ARGS	Ignores `[count]` and does not accept arguments. Use the event name alone.

Event reference

Combat and damage

Event	Policy	Description	Key arguments
`KILL_PLAYER`	NORMAL	Player kills another player.	`NAME_EXACT`, `NAME_CONTAINS`, `NAME_REGEX`, `PERMISSION` (victim filters).
`DAMAGE_PLAYER`	NORMAL	Player damages another player.	Same arguments as `KILL_PLAYER`.
`KILL_MOB`	NORMAL	Player kills a mob.	`TYPE_EXACT`, `TYPE_CONTAINS` (entity interfaces), `NATURE` (`PASSIVE`, `NEUTRAL`, `HOSTILE`), `CATEGORY` (`UNDEAD`, `ARTHROPOD`, `ILLAGER`, `WATER`, `NONE`).
`DAMAGE_MOB`	NORMAL	Player damages a mob.	Same arguments as `KILL_MOB`.
`DYING`	NO_ARGS	Player death trigger (useful for penalties).	—

Block and item interactions

Event	Policy	Description	Key arguments
`BREAK_BLOCK`	NORMAL	Block broken by a player.	`TYPE_EXACT`, `TYPE_CONTAINS` (block interfaces such as `FALLING_BLOCK`).
`PLACE_BLOCK`	NORMAL	Block placed by a player.	Same as `BREAK_BLOCK`.
`CRAFT`	NORMAL	Item crafted.	`TYPE_EXACT`, `TYPE_CONTAINS` (material names).
`CONSUME`	NORMAL	Item consumed.	Same as `CRAFT`.
`FISH`	NORMAL	Fishing catch.	Same as `CRAFT`.
`BREW`	NORMAL	Brewing stand completion.	`EFFECT` (potion effect key).
`ENCHANT`	NORMAL	Item enchanted.	`ENCHANTMENT` (key or legacy name), `LEVEL` (range).
`SMELT`	EXCESSIVE	Items removed from a furnace-like block.	`ITEM` (material), `FURNACE_TYPE` (`FURNACE`, `BLAST_FURNACE`, `SMOKER`, `FURNACE_MINECART`).
`REPAIR_ITEM`	NORMAL	Item repaired via anvil or grindstone.	`ITEM` (material).
`DROP_ITEM`	EXCESSIVE	Item stack dropped.	`ITEM` (material). Hit count equals stack size.
`PICKUP_ITEM`	EXCESSIVE	Item stack picked up.	`ITEM` (material). Hit count equals stack size.

Farming, mobs, and world

Event	Policy	Description	Key arguments
`BREED`	NORMAL	Animals bred.	`TYPE` (entity type).
`TAME_ENTITY`	NORMAL	Entity tamed.	`TYPE` (entity type).
`SHEAR_SHEEP`	NO_ARGS	Sheep sheared.	—
`MILK_COW`	NO_ARGS	Cow milked.	—
`ADVANCEMENT`	IGNORED	Advancement obtained.	`KEY` (namespace, e.g., `minecraft:adventure/kill_a_mob`).
`WORLD_CHANGE`	NORMAL	Player switches worlds.	`NAME_EXACT`, `NAME_CONTAINS`, `TYPE` (`NORMAL`, `NETHER`, `THE_END`).
`JOIN`	NO_ARGS	Player joins the server.	—
`QUIT`	NO_ARGS	Player leaves the server.	—

Economy, quests, and miscellaneous

Event	Policy	Description	Key arguments
`RUN_COMMAND`	NORMAL	Player executes a command.	`CONTAINS`, `EXACT` (raw command text).
`TRADE_VILLAGER`	NORMAL	Villager trade completed.	`ITEM` (output), `PROFESSION`, `LEVEL` (villager level range), `BIOME` (villager type).
`MOVE`	NO_ARGS	Player moves from one block to another.	—
`JUMP`	NO_ARGS	Jump action.	—
`SNEAK`	NO_ARGS	Sneak toggle.	—
`SPRINT`	NO_ARGS	Sprint toggle.	—
`SWIM`	NO_ARGS	Swim toggle.	—
`CHAT`	EXCESSIVE	Chat messages sent.	`MESSAGE_CONTAINS`, `MESSAGE_EXACT`.
`TIMED_EXP`	NO_ARGS	Awards EXP on a timer (e.g., `TIMED_EXP[300]`).	—
`EXP_GAIN`	IGNORED	Vanilla EXP gain.	`EXP` (range of raw XP).
`LEVEL_UP`	IGNORED	Vanilla level increase.	`LEVEL` (range).
`UNKNOWN`	NO_ARGS	Fallback event. Use only for debugging invalid identifiers.	—

Where to use events

Declare sections inside exp-events.yml.
Reference expressions in level requirements, reward conditions, or booster filters when those systems mention EXP events.
Document your sections in team handbooks so administrators understand which gameplay loops feed each leveling system.

Need inspiration?

Walk through the Experience Design guide for ideas on grouping events, then apply cooldowns and requirements with the configuration articles linked above.

Event Catalog

On this page