Content generated with AI — it may contain mistakes.

ExyliaSandBox/ReferencedevUpdated in v1.2.0

API

Ask where a player is, send them into a world, read the worlds and their kits, dress them, read their sandbox statistics, and the join, arrive and leave events.

Page 17 of 246 min read

SandBoxService is how another plugin asks whether a player is in a sandbox or a queue, sends them into a world, reads the configured worlds and a player's saved kits, dresses somebody in one of them, and reads their kills, deaths and playtime. Three events tell it when a player asks to come in, lands and leaves.

java
ExyliaAPI.get(SandBoxService.class).ifPresent(sandbox -> {
    if (sandbox.isInSandbox(player.getUniqueId())) {
        event.setCancelled(true);
    }
});
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.

The claim is the answer, not the world#

isInSandbox answers from the session claim the plugin takes, not from the world the player is standing in. The two disagree for the length of every unfinished teleport, and the claim wins — which is what you want: a player who has been claimed and is mid-flight is already busy.

Everything that returns a value reads a cache and is safe from a placeholder, a scoreboard line or a menu redraw. Everything that acts teleports players and rewrites inventories: call those on the main thread, and no more often than a player could trigger them.

Session#

MethodWhat it does
boolean isInSandbox(UUID)Whether they hold the sandbox claim.
boolean isInQueue(UUID)Whether they are waiting for an opponent.
boolean leave(Player)Sends them back to the lobby. Reports whether the request was accepted, not whether it finished; false while they are building a kit.
boolean joinQueue(Player, String worldId, int kitSlot)Queues them for one world. false only when no world is configured under that id — anything else the queue refuses is said to the player.
void leaveQueue(Player)Takes them out of whichever queue they are in.
EnterResult enter(Player, String worldId, int kitSlot)Sends them straight into a world, dressed in one of their kits — the /rtp way in.
void openWorldSelector(Player)Opens the world list /rtp opens: the screen a lobby NPC wants.

enter decides every refusal before anything is taken from the player, and says none of them to the player: the result is yours to put into words. ACCEPTED is a request under way, not an arrival — finding a safe spot and landing the teleport end some ticks later and can still fail, in which case the player is given back as they were and told so. SandboxArriveEvent is the confirmation.

EnterResultMeaning
ACCEPTEDOn their way in
BUSYAnother plugin holds them, or they are building a kit
ALREADY_IN_SANDBOXMoving between sandbox worlds is not entering one
UNKNOWN_WORLDNo world is configured under that id
WORLD_NOT_READYStill generating, or unavailable
NO_KITThe slot holds no saved kit with anything in it
REFUSEDA SandboxJoinEvent handler cancelled it, the player is combat-tagged (they are told general.in-combat), or another plugin took them between the checks and the claim

openWorldSelector opens whether or not the player could enter right now: a world that is not ready draws without an action, and every way in the screen offers makes its own checks when clicked.

Worlds#

MethodWhat it does
List<SandboxWorld> worlds()Every configured world, unusable ones included, in no particular order. Unmodifiable.
Optional<SandboxWorld> world(String worldId)One by id.
Optional<SandboxWorld> worldOf(World)The listener's question: is this Bukkit world one of ours?
float pregenerationProgress(String worldId)0 to 1. 0 for a world that has finished as well as one that never started.

SandboxWorld is a snapshot, not a live view: id, displayName, worldName, biome, borderSize, type, status and loaded, plus isPlayable() — loaded and READY. It carries a world name rather than a World because a configured world is not necessarily loaded.

WorldStatus is CREATING, PREGENERATING, READY or UNAVAILABLE. WorldType is MANAGED or IMPORTED.

Kits#

MethodWhat it does
List<SandboxKit> kits(UUID)Their saved kits, ordered by slot. An offline player reports nothing. Unmodifiable.
Optional<SandboxKit> kit(UUID, int slot)One slot.
Optional<SandboxKit> favoriteKit(UUID)The starred one, if they have one.
int maxKits(Player)How many slots they are allowed. Reads permissions, so it takes the player.
int activeKitSlot(UUID)The slot they are wearing, -1 when they are wearing none.
void applyKit(Player, int slot)Replaces what they carry with that kit. A no-op on an unused slot.

SandboxKit is slot, name, favorite, hasContents, createdAt and updatedAt. The contents are deliberately not exposed — use applyKit rather than reading the stacks.

Statistics#

MethodWhat it does
SandboxStats stats(UUID)Never empty. A player nothing has loaded reads as zeroes, and the read is started, so the next draw has the numbers.

SandboxStats is player, kills, deaths and playtimeMillis, plus kdr() — which returns the kill count when there are no deaths. Playtime is sandbox time only, not time on the server.

Events#

All three live in net.exylia.lib.api.sandbox.event, carry getPlayer() and getWorld() (a SandboxWorld), and are called on the thread that owns the player, which on Folia is their region thread.

EventWhenCancellable
SandboxJoinEventA player asks for a world, by random teleport or by joining its queue, before anything is taken from them. getKitSlot() and isQueued() say how.Yes: they are left exactly as they were, and the plugin says nothing
SandboxArriveEventThey have landed, in survival with full health and their kit on. The confirmation the other two are not.No
SandboxLeaveEventThe sandbox has let go of them: inventory back, claim released. getReason() is LEFT, DIED or DISCONNECTED.No

A queue asks once, when the player joins it, not again when a partner is found — refusing then would send the partner in alone. Moving from one sandbox world to another fires none of the three, and neither does logging back in inside one. Leaving a queue, or a way in that failed before the player arrived, does not fire SandboxLeaveEvent. Cancelling a join says nothing to the player: telling them why is the canceller's job.

Something missing on this page? Tell us on Discord