Content generated with AI — it may contain mistakes.

ExyliaArrows/ReferenceUpdated in v1.7.1

API

Play effects, bind them to bows and read what a player owns from your own plugin.

Page 15 of 2210 min read

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.

java
ExyliaAPI.get(ArrowsService.class).ifPresent(arrows -> {
    arrows.select(player, "storm");
    arrows.effectItem("storm").ifPresent(item -> player.getInventory().addItem(item));
});
Adding it to your project

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#

MethodWhat 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#

MethodWhat 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#

MethodWhat 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 sets, and does not ask for a node

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#

MethodWhat 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#

MethodWhat 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#

MethodWhat 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#

MethodWhat 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.

MethodWhat 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#

MethodWhat 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.

java
@EventHandler
public void onArrowEffect(ArrowEffectPlayEvent event) {
    if (event.getLocation().getWorld().getName().equals("lobby")) event.setCancelled(true);
}
MethodWhat 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.

Queries are cheap, actions are not

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