API
Play effects, bind them to bows and read what a player owns from your own plugin.
ArrowsService is what another plugin reads and drives ExyliaArrows through: the catalogue and its
categories, the effect a player chose, their shortlist and particle setting, the effects bound to
bows, effects played on demand, the menus, unlocks and crate keys.
ExyliaAPI.get(ArrowsService.class).ifPresent(arrows -> {
arrows.select(player, "storm");
arrows.effectItem("storm").ifPresent(item -> player.getInventory().addItem(item));
});The artifact, the repository and the plugin.yml line are the same for every Exylia plugin and live
on the public API page. Playing an effect, the menus, unlocks, keys and
ArrowEffectPlayEvent arrived in exylia-api v1.133.0 and ExyliaArrows 1.4.0: compile against
that tag or a newer one to reach them.
The service is registered with Bukkit's ServicesManager when ExyliaArrows enables. Treat an empty
result from ExyliaAPI.get as "arrow effects are not part of this server", not as a failure.
Everything is addressed by effect id, matched without regard to case. An id the catalogue does
not declare is not an error — a reload can remove one while a crate still hands it out — so lookups
answer empty and writes answer false.
The catalogue#
| Method | What it does |
|---|---|
effects() | Every effect the server declares, in the order a menu draws them. A snapshot: fine for building a shop, wasteful in a loop. |
effect(String effectId) | One effect as an Optional<ArrowEffect>. Empty when the catalogue declares no such id. |
exists(String effectId) | Whether the catalogue declares that id. |
categories() | Every category, in the order the menu draws its tabs. |
category(String categoryId) | One category as an Optional<ArrowCategory>. Empty when the catalogue declares no such id. |
effectsIn(String categoryId) | The effects in one category, in menu order. Empty when the category does not exist. |
Permissions#
| Method | What it does |
|---|---|
canUse(Player, String effectId) | Whether they may use the effect. |
Answers by the server's own rule: the effect's node, the node for its whole category or its rarity, the wildcard, or an unlock from the crate or the shop. A shop asking gets the same answer the menu would give, not a raw permission check.
What the player chose#
| Method | What it does |
|---|---|
mode() | Where the effects this server plays come from, as an EffectMode. |
selected(UUID player) | Their chosen effect id, as an Optional<String>. Empty when they chose none, the menu is off, or their row is still being read. |
select(Player, String effectId) | Sets the effect that follows them. true when it was stored. |
clear(Player) | Takes their own choice away, back to the server's default for their rank. It is not an opt-out: only the player turning their effect off in the menu records that. |
select is a set rather than a toggle: running it twice leaves the effect on. It is not gated by
permission, because an effect handed out by a crate or a reward is owned whether or not a node was
ever granted for it. Ask canUse first when you do want the permission to decide.
Favourites#
| Method | What it does |
|---|---|
favourites(UUID player) | The effect ids they starred, in the order they starred them. Empty when they starred none or are still being read. |
isFavourite(UUID player, String effectId) | Whether one effect is starred. |
toggleFavourite(Player, String effectId) | Stars an effect, or unstars it when it is already starred. true when the id named an effect that exists. |
clearFavourites(Player) | Unstars everything. |
The shortlist keeps the player's own order rather than the catalogue's — somebody built it, and
re-sorting it takes that away. toggleFavourite is deliberately a toggle rather than a pair of
methods: the star is one control with two states, and a caller that had to read the state first would
race the player clicking it.
Particle visibility#
| Method | What it does |
|---|---|
visibility(UUID player) | Who currently sees their arrow particles. ParticleVisibility.ALL when they never changed it or are still being read. |
setVisibility(Player, ParticleVisibility) | Stores who sees them. |
Effects on items#
| Method | What it does |
|---|---|
boundTo(ItemStack bow) | The effect id bound to that bow, crossbow or trident, as an Optional<String>. Empty when it carries none. |
bind(ItemStack bow, String effectId) | Binds an effect to the bow in place, keeping everything else it had. Refused when the item is not something an effect can be bound to, or when the effect declares itself not to fit it. |
unbind(ItemStack bow) | Takes the effect off and gives nothing back. true when an effect was there. |
effectItem(String effectId) | An effect token ready to be given out, as an Optional<ItemStack>. Empty when the catalogue declares no such effect. |
isEffectItem(ItemStack) | Whether an item is one of this plugin's effect tokens. |
Ask isEffectItem before a container, a shop or a trade treats a stack as ordinary loot: a token is
drawn as whatever suits what it carries and is not the material it looks like.
Playing an effect#
| Method | What it does |
|---|---|
boolean play(String effectId, ArrowTrigger trigger, Location where, Player shooter, @Nullable Entity hit) | Plays one moment of an effect at a place, as though a shot were there. The region flag, ArrowEffectPlayEvent and every observer's own visibility still decide; the bow, the menu choice, the projectile types and permission are skipped, because the caller named the effect. Exactly the moment asked for: a HIT_ENTITY on an effect that only declares HIT draws nothing. false when no effect goes by that id, it draws nothing then, the region silences it or a listener cancelled it. Call it on the thread that owns where. |
boolean attach(Projectile projectile, String effectId) | Makes a projectile carry an effect, as though it had just been fired with it — an ability's volley, a turret, a spell drawn as an arrow. The launch plays where it is now, the trail follows it and the impact plays where it lands; an effect it already carried is replaced. The shooter has to be a player. Call it straight after spawning the projectile, on the thread that owns it. |
boolean preview(Player viewer, String effectId) | Shows the effect on the server's preview stage, the way the menu's right click does. Owning it is not required, which makes it a shop's "try before you buy". false, and the player told so, when no stage is set. |
ArrowTrigger is LAUNCH, TRAIL, HIT or HIT_ENTITY.
Menus#
| Method | What it does |
|---|---|
void openMenu(Player player) | Opens the effect menu exactly as /arrows does, for an NPC, a hub item or a shop. The player's row is read first when it is not in memory, so the menu can appear a moment after the call. On a bow server the player is told the menu is off. Safe from any thread. |
void openCrate(Player player) | Opens the crate exactly as the command and the crate blocks do: the screen that asks how many to open and spends keys. With the crate turned off the player is told so. Safe from any thread. |
Owning, and crate keys#
| Method | What it does |
|---|---|
boolean unlock(Player player, String effectId) | Gives a player an effect for good, as winning it from the crate does — ownership without a permission node, counted by canUse from then on. Nothing is chosen and no item is given: follow it with select or effectItem for that. false when no effect goes by that id, they already own it that way, or their row has not arrived yet. |
int keys(UUID player) | How many crate keys a player holds. 0 when they have none or their row has not arrived yet. |
void addKeys(Player player, int keys) | Gives keys, or takes them with a negative number — how a store, a vote or a quest pays out a spin. The count never goes below zero. |
ArrowEffectPlayEvent#
net.exylia.lib.api.arrows.event.ArrowEffectPlayEvent fires once everything else has agreed a moment
should play: the effect draws something then, and the region allows arrow effects. It fires once per
moment — the launch, the start of the trail, the impact — for real shots and for play and attach
alike, and the two are not told apart on purpose: an arena that wants arrow effects quiet wants both
quiet.
@EventHandler
public void onArrowEffect(ArrowEffectPlayEvent event) {
if (event.getLocation().getWorld().getName().equals("lobby")) event.setCancelled(true);
}| Method | What it returns |
|---|---|
Player getPlayer() | The shooter: whose effect it is. |
@Nullable Entity getHitEntity() | What the shot landed on. null for a launch, a trail, a block, or a play that named nothing. |
String getEffectId() | The effect about to play, normalised. |
ArrowTrigger getTrigger() | Which moment it is. |
Location getLocation() | Where it plays; for a trail, where the line starts. A copy: changing it moves nothing. |
Cancelling draws nothing and says nothing; the shot itself flies and lands as it would have.
Cancelling a TRAIL stops the whole line for that shot. The event is called on the thread that owns
the location, which on Folia is a region thread rather than the main one.
Types#
ArrowEffect — id, categoryId, name (colour codes still in it), permission (the node
granting this one effect) and description (the owner's own words, line breaks and all). What the
effect draws is deliberately absent: it is a compiled sequence belonging to the plugin that plays
it.
ArrowCategory — id, name, permission. Its node grants every effect inside it at once,
which is how a rank is sold as "every storm effect" without listing them one by one.
EffectMode — where a played effect comes from: PLAYER (only what the player picked; a bow
carries nothing), BOW (only what is bound to the bow; the menu chooses nothing) or BOTH.
usesBows() and usesMenu() answer without a switch. Worth asking before writing anything: the half
a server does not use answers false or empty rather than throwing, so an integration written for
both runs on either.
ParticleVisibility — ALL, NONE, SELF_ONLY, OTHERS_ONLY. A player's own setting, not a
server one. The label each mode is shown under is written by the server owner and is not carried
here: a constant is an identity, not a name.
Everything returning a value reads the plugin's cache and is safe from a menu redraw or a placeholder — a player who has not finished loading reads as one who chose nothing, which is why every read answers rather than waits. Everything that changes a player's choice writes to the database, so call those on the main thread and no more often than a player could.
What it does not expose#
One event, ArrowEffectPlayEvent. What an effect draws (its compiled sequence) is left out on
purpose, and so are the plugin's configuration and internal classes: a public contract cannot be
broken later, so it carries what an integration needs and nothing that only made sense inside one version.
If something you need is genuinely missing, ask on Discord.
Something missing on this page? Tell us on Discord