Skip to content

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
}
EventFiredCancellableNotes
PrePlayerVanishEventBefore vanish is applied.✅isOnJoin() is true when triggered by PlayerJoinEvent.
PlayerVanishEventAfter vanish is fully applied (visibility, potions, flight).❌Same isOnJoin() flag.
PrePlayerUnvanishEventBefore unvanish is applied.✅isOnLeave() is true when triggered by PlayerQuitEvent.
PlayerUnvanishEventAfter unvanish is fully applied.❌Same isOnLeave() flag.

❤️‍🩹 Best practices

  1. Always go through ZelVanishProvider.get() — never reflect into com.zeltuv.zelvanish.internal.*. That package is obfuscated and the symbol names change across releases.
  2. Don't mutate the returned collections. getVanishedPlayerIds() and getOnlineVanishedPlayers() return immutable snapshots; copy if you need a mutable structure.
  3. Listen, don't poll. Subscribe to the events instead of running scheduled tasks against isPlayerVanished().
  4. Veto with the Pre… events. State mutations and visibility are already in progress in the post events; cancellation has no effect there.
  5. 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.