ZelVanish
Developer API
I) Adding ZelVanish as a dependency
Maven
<repository>
<id>repsy.io/</id>
<url>https://repo.repsy.io/mvn/zeltuv/zelvanish</url>
</repository>
<dependency>
<groupId>com.zeltuv</groupId>
<artifactId>zelvanish-api</artifactId>
<version>1.0.0</version>
<scope>provided</scope>
</dependency>
Gradle
repositories {
mavenCentral()
maven { url 'https://repo.repsy.io/mvn/zeltuv/zelvanish' }
}
dependencies {
compileOnly 'com.zeltuv:zelvanish-api:1.0.0'
}
Add ZelVanish to your plugin's softdepend in plugin.yml so it loads first.
II) Accessing the API
ZelVanish exposes a single interface, ZelVanishApi, obtained from ZelVanishProvider. Both live in the com.zeltuv.zelvanish.api package, which is excluded from obfuscation — symbol names are stable across releases.
import com.zeltuv.zelvanish.api.ZelVanishApi;
import com.zeltuv.zelvanish.api.ZelVanishProvider;
ZelVanishApi vanish = ZelVanishProvider.get();
ZelVanishProvider.get() throws IllegalStateException if ZelVanish isn't loaded yet, gate your initial calls on onEnable after the plugin loader has run.
🩵 The ZelVanishApi interface
State changes
// Vanish a player. Returns true if the state changed.
boolean changed = vanish.vanishPlayer(player);
// onJoin = true suppresses the vanish broadcast and delays potion effects
// so they survive the join sequence.
vanish.vanishPlayer(player, true);
// Unvanish. onLeave = true suppresses the unvanish broadcast.
vanish.unvanishPlayer(player);
vanish.unvanishPlayer(player, true);
// Flip and return the new state.
boolean nowVanished = vanish.toggleVanish(player);
Queries
boolean hidden = vanish.isPlayerVanished(player);
boolean hidden = vanish.isPlayerVanished(playerUuid);
// Whether viewer should be able to see target.
boolean visible = vanish.canSee(viewer, target);
int total = vanish.getVanishedPlayerCount(); // all known vanished IDs
int onlineVanished = vanish.getOnlineVanishedPlayerCount(); // online subset
int publicCount = vanish.getVisibleOnlinePlayerCount(); // what /list / scoreboard should show
Set<UUID> ids = vanish.getVanishedPlayerIds(); // immutable snapshot
List<Player> on = vanish.getOnlineVanishedPlayers(); // immutable snapshot
🪝 Events
All four events fire on the Bukkit event bus and respect the standard @EventHandler priorities. The two Pre… events are Cancellable ; cancel them to veto the action.
import com.zeltuv.zelvanish.api.event.PrePlayerVanishEvent;
import com.zeltuv.zelvanish.api.event.PlayerVanishEvent;
import com.zeltuv.zelvanish.api.event.PrePlayerUnvanishEvent;
import com.zeltuv.zelvanish.api.event.PlayerUnvanishEvent;
@EventHandler
public void onPreVanish(PrePlayerVanishEvent event) {
if (event.getPlayer().getWorld().getName().equals("pvp")) {
event.setCancelled(true); // veto vanishing in PvP world
}
}
@EventHandler
public void onVanish(PlayerVanishEvent event) {
Player p = event.getPlayer();
boolean fromJoin = event.isOnJoin();
// post-vanish hook
}
@EventHandler
public void onUnvanish(PlayerUnvanishEvent event) {
Player p = event.getPlayer();
boolean fromQuit = event.isOnLeave();
// post-unvanish hook
}
| Event | Fired | Cancellable | Notes |
|---|---|---|---|
PrePlayerVanishEvent | Before vanish is applied. | ✅ | isOnJoin() is true when triggered by PlayerJoinEvent. |
PlayerVanishEvent | After vanish is fully applied (visibility, potions, flight). | ❌ | Same isOnJoin() flag. |
PrePlayerUnvanishEvent | Before unvanish is applied. | ✅ | isOnLeave() is true when triggered by PlayerQuitEvent. |
PlayerUnvanishEvent | After unvanish is fully applied. | ❌ | Same isOnLeave() flag. |
❤️🩹 Best practices
- Always go through
ZelVanishProvider.get()— never reflect intocom.zeltuv.zelvanish.internal.*. That package is obfuscated and the symbol names change across releases. - Don't mutate the returned collections.
getVanishedPlayerIds()andgetOnlineVanishedPlayers()return immutable snapshots; copy if you need a mutable structure. - Listen, don't poll. Subscribe to the events instead of running scheduled tasks against
isPlayerVanished(). - Veto with the
Pre…events. State mutations and visibility are already in progress in the post events; cancellation has no effect there. - Respect
canSee()in your own hide/show logic if your plugin manipulates player visibility (e.g. spectator hubs, party plugins). It encodes the same rules ZelVanish uses internally.
🛠️ Support
For additional support, feature requests, or bug reports, reach out on our Discord.