Content generated with AI — it may contain mistakes.

ExyliaLib/Gameplay

Players

One claim registry, stays, cooldowns local and network-wide, alts, placed blocks, teleports, snapshots, clans, combat and heads.

Page 42 of 5410 min read

One player, one activity#

The problem this solves: three minigames on one server, each with a isInGame(player) method, each asking the other two by reflection, each answering about a moment that had already passed by the time the join ran.

java
PluginSessions sessions = Sessions.of(this);
 
if (!Sessions.isFree(player)) {
    Sessions.holder(player).ifPresent(claim ->
            Text.of("Busy in " + claim.kind()).send(player));
    return;
}
 
sessions.claim(player, "Event", () -> { leaveEvent(player); return true; })
        .ifPresent(claim -> join(player));
CallWhat it does
Sessions.isFree(player)Whether anything holds them. A question, not a reservation.
Sessions.holder(player)Who holds them, and what they called it.
sessions.claim(player, kind, onRelease)Take them. Atomic — this is what actually decides.
sessions.mine(player)The claim, if it is ours.
sessions.release(player)Give them back: ends our claim, never another plugin's.
Sessions.release(player)Ask whoever holds them to give them back.
isFree is not a reservation

Between asking and acting, somebody else may have taken the player. claim is the one that decides, and it returns empty when it lost the race. The release callback is how whoever holds them is told to let go.

The release callback returns whether the request is accepted, not whether it has finished: handing a player back is a teleport and a restore, which end later, so an accepting handler releases the claim from its own callback. Returning false refuses — a player in combat is not available — and the asker is told no. A claim taken with no callback is dropped outright when somebody asks.

Work that finishes later is fenced against the claim, so it cannot touch a player who has since moved on:

java
teleport(player, spawn).thenRun(() -> claim.ifCurrent(() -> giveKit(player)));

The claim is re-entrant for its owner: a player moving from an event's lobby into the game, or from playing into spectating, keeps one continuous claim rather than releasing and racing to retake it. A claim also ends when the player disconnects or its plugin is disabled.

Nothing in the registry knows which modes exist, so a mode added later is covered without touching it.

Stays#

Most claims mean "take them into my arena and give them back as they came". Stays is that, with the three orderings every arena plugin had to learn the hard way built in:

java
PluginStays stays = Stays.of(this);
 
// In: claimed and saved here, emptied once they stand in the arena.
stays.enter(player, "duel", () -> { endMatch(player); return true; }).ifPresent(stay ->
        stay.ready().thenCompose(ignored -> teleport(player, arena))
                .thenCompose(ignored -> stays.dress(player, GameMode.ADVENTURE, stay::isCurrent)));
 
// Out: home, restored there, released last.
stays.leave(player);
 
// On join: whatever a crash left behind goes back, and so does the player.
stays.recover(player);
CallWhat it does
enter(player, kind, onRelease)Claims the player and saves a snapshot of them. stay.ready() completes once it is stored — the cue to move them.
enter(player, claim)Turns a claim this plugin already holds into a stay (a queue moving its player into the match). Keeps the claim's token and handler.
dress(player, mode, still)Empties them and sets their game mode, on arrival. Skipped when still says they are no longer wanted.
leave(player) / leave(player, home)Back where they came from (or to a lobby), restored there, then released.
leaveHere(player)Restored where they stand, for a player who walked out through a portal.
recover(player)Gives back every stored stay a crash or restart left behind. Call on join.
isHeld(uuid)Whether this plugin answers for their belongings: held, or still on the way out.
  • The snapshot is taken before the teleport and the inventory emptied only after it, because a per-world inventory plugin writes whatever the player holds into the world they leave.
  • A restore never starts before its save has landed.
  • The claim is released last, so nothing else can dress the player while their things are still on the way back.

Cooldowns#

The base every cooldown in the ecosystem sits on, so a bar can display one without owning it:

java
PluginCooldowns cooldowns = Cooldowns.forPlugin(this);   // keys become "myplugin:pearl"
 
cooldowns.startSeconds(player, "pearl", 16);
cooldowns.isActive(player, "pearl");
cooldowns.remainingSeconds(player, "pearl");
cooldowns.tryStart(player, "pearl", Duration.ofSeconds(16));   // false while running

CooldownScope widens the key beyond one player — CooldownScope.GLOBAL, CooldownScope.group(clanId) or any CooldownScope.of(type, id). Cooldowns of five minutes or more are written to disk and come back after a restart; shorter ones live in memory.

ItemCooldowns puts the vanilla cooldown sweep on an item at the same time, so the client greys it out. On Lunar and the SurvivalCore mod the cooldown is also drawn on the HUD with the item as its icon — see Client integration.

Items that share a material: separate(stack, group) (Minecraft 1.21.4+) gives a stack its own cooldown group, and start/clear/redraw(player, key, ItemStack, ...) draw on that group, so a custom pearl on cooldown leaves other pearls free. Vanilla restarts a sweep after the item is used; started during that use, redraw a tick later.

An effect can read a running cooldown instead of counting on its own — see Effects · Timers.

Across relogs and servers#

Cooldowns belongs to one server's memory: a player who quits or switches server starts a thirty-second cooldown over. For anything worth abusing — a repair, a heal, a kill reward — use NetworkCooldowns, written to the plugin's database so every server sharing it sees the same one:

java
NetworkCooldowns cooldowns = NetworkCooldowns.of(this);   // once, in onEnable
 
if (!cooldowns.tryStart(player.getUniqueId(), "repair", Duration.ofMinutes(10))) {
    if (!cooldowns.isLoaded(player.getUniqueId())) { say(player, "Still loading."); return; }
    say(player, "Wait " + cooldowns.remaining(player.getUniqueId(), "repair").toSeconds() + "s.");
    return;
}

A player's cooldowns are read when they join and answered from memory afterwards. Until that read is back the answer is "wait": isActive is true and tryStart is false, so a player cannot slip through the gap a server hop opens. start and clear change memory at once and are written in the order they were made. Rows live in exylia_network_cooldowns and are deleted when cleared or when the owner next joins after they ended.

Alts and first joins#

Accounts answers whether two accounts are likely the same person, and how long the network has known a player — online or not:

java
Accounts accounts = Accounts.of(this);   // once, in onEnable
 
accounts.sameAddress(buyer, seller).thenAccept(alt -> {
    if (alt) return;   // no reputation between a player and their alt
    ...
});
accounts.firstSeen(invited).thenAccept(first -> ...);   // Optional<Instant>
  • The address itself is never stored. Every join writes a keyed hash of it, with when it was last used, plus the earliest time the player was seen. The key lives in the database, so every server sharing it hashes an address the same way. An IPv6 address is hashed by its /64.
  • sameAddress counts an address both players used within the last 30 days (accounts.window(…) changes it), or both being online here from the same address right now.
  • firstSeen also takes the server's own first-played date, so a veteran is not "new" the first time this module sees them.
  • Both complete exceptionally when the database cannot answer. Decide what that means: a reward should refuse (.exceptionally(failure -> true)), a warning should stay quiet.

Point every server's plugin at one database and the answers are network-wide.

Placed blocks#

Whether a block was put there by a player, remembered across restarts — the anti-farming question:

java
PlacedBlocks.track(this, List.of(Material.SUGAR_CANE, Material.DIAMOND_ORE));
 
@EventHandler(ignoreCancelled = true)
public void onBreak(BlockBreakEvent event) {
    if (PlacedBlocks.placedByPlayer(event.getBlock())) return;   // no reward for place-and-break
    reward(event.getPlayer());
}

The record lives in the chunk's own data, so it is saved and loaded with the blocks and costs nothing while the chunk is unloaded. Only tracked materials are recorded; a piston moves the record with the block, and breaking it forgets it only after every listener below MONITOR has asked. A block that leaves another way (explosion, burning) keeps its record — the answer errs on "placed". Each chunk keeps at most 4096 positions.

Numbers in permissions#

java
int homes = PermissionNumbers.highest(player, "myplugin.homes.", settings.defaultHomes());

The largest number behind a prefix wins, because a rank ladder grants every step on the way up. A node set to false grants nothing, and a tail that is not a whole number is ignored. Call it on the player's own thread.

Placeholder arguments in commands#

For any other one-word value with characters Brigadier refuses (a placeholder such as %top_kills;name;1%), use command.lamp.TokenArgument (since 1.583.0): it reads the same way and tells the client it is a player name, the one vanilla type the client also reads up to the next space, so nothing is drawn in red.

Teleports#

Moving a player is rarely just player.teleport(...):

java
PluginTeleports teleports = Teleports.of(this);
 
teleports.to(player, spawn)
         .warmup(3.0)
         .cancelOnMove()
         .cancelOnDamage()
         .cooldown("spawn", 30.0)
         .safe()
         .start();
CallWhat it does
to(player, location)A request, configured then started with start(). Nothing happens before that, and the cooldown is only charged then.
toAll(players, location)A group at once.
back(player)A request to where they were before the last teleport.
lastLocationOf(player)That location, without moving them.
request(from, to, …)A /tpa-style request.
accept(target, from) / deny(…) / cancel(…)Answering one.

A request can also play effects (onStart, onArrive, onCancel), report the countdown (onTick) and hand back the result (then). Warmups, safe landings, /back history and cross-server handovers all live here, and every one of them runs on the player's own thread.

Snapshots#

A player's state kept for later — in memory while a menu is open, or stored so it survives a restart:

java
PluginSnapshots snapshots = Snapshots.of(this);
 
Snapshot held = snapshots.capture(player);            // in memory, right now
snapshots.saveAndClear(player, "event:lms1");         // stored, and the player emptied
snapshots.restore(player, "event:lms1");              // given back

capture is the in-memory one for a menu that will hand the state back in a moment. save writes it under a context id so it survives a restart, and saveAndClear does both halves of "put this away and give them the kit" in one call.

It is what gives a player their survival inventory back after an event, and what lets a kit editor hand back what somebody was carrying when they opened it. Stays are built on it.

Clans#

One API over eight clan plugins, detected automatically at startup:

java
if (Clans.isSupported()) {
    Optional<String> tag = Clans.clanTag(player.getUniqueId());
    Optional<Clan> clan  = Clans.clanOf(player.getUniqueId());
}

Detection order — the first one present and reachable wins:

  1. FactionsUUID / Factions
  2. HuskTowns
  3. ZelTeams
  4. RunithClans
  5. UltimateClans
  6. Kingdoms / KingdomsX
  7. SimpleClans
  8. ExyliaClans

Every provider reaches its plugin by reflection, so one that is installed but whose API cannot be reached is skipped with a warning rather than taking the slot silently. A plugin not on the list registers a ClanBridge, and a registered bridge beats automatic detection.

Alliances and rivalries are part of the API (areAllied, areRivals), and providers that have no concept of them answer empty rather than guessing.

Combat#

Whether a player is fighting, over DeluxeCombat, PvPManager or a bridge you write:

java
if (Combat.isTagged(player)) {
    return;
}

The point is the same as clans: your plugin asks one question and does not care which plugin answers. With nothing installed every call still works: nobody is tagged and PvP is always allowed.

Bedrock players#

java
if (Clients.isBedrock(player)) {
    // skip what a Bedrock client cannot draw, such as display entities
}

Floodgate answers when it is installed, since only it knows a linked player; otherwise the UUID does, the way Geyser recommends, and Geyser's own API is asked when it runs without Floodgate. The name is never used. It works whichever of the two enables first. A linked player who is offline cannot be told apart from their Java account and answers false.

Heads#

java
Skulls.player("Notch").build();
Skulls.texture(base64).build();
Skulls.url(url).build();

Cached, shared across plugins, and never blocking: a head that has not been fetched yet comes back plain and is replaced when it arrives. That is why a menu full of player heads opens instantly instead of freezing the server on a Mojang lookup.

Preferences#

Player toggles and the /settings screen every plugin registers into have their own page: Player settings.

Something missing on this page? Tell us on Discord