Developer API - SnVanishRegion Docs

SnVanishRegion exposes a public developer API for other plugins: custom Bukkit events and a read-only query service. The API lives in the com.sn.vanishregion.api package inside the plugin jar. There is no separate artifact.

Only com.sn.vanishregion.api is a stable, kept contract. Everything else in the jar is obfuscated and internal. Do not call it.

Getting the jar

Download the latest release jar.

Install it into your local Maven repository:

mvn install:install-file -Dfile=SnVanishRegion-<version>.jar -DgroupId=com.sn \
  -DartifactId=SnVanishRegion -Dversion=<version> -Dpackaging=jar

Depend on it with provided scope. Never shade it.

Quick start

Declare the dependency in your plugin.yml:

depend: [SnVanishRegion]      # or softdepend if optional

Resolve the API when you need it:

SnVanishRegionAPI api = SnVanishRegionProvider.get();
if (api != null) {
    // use the api
}

Resolve the reference when you need it. Do not cache it across a SnVanishRegion reload.

Master switch

API events can be disabled by the server owner with api-events.enabled: false in config.yml. The query service stays available either way.

Events

Cancellable events fire before the action. Cancelling aborts it. The plugin sends no message when you cancel, so tell the player why yourself.

Event	Fired when	Cancel effect
`RegionCreateEvent`	A player runs `/vanishregion create`, just before the region is stored. Not fired when `regions.yml` cannot be saved.	The region is not created and nothing is saved.
`RegionDeleteEvent`	A region is about to be deleted with `/vanishregion delete`. `getPlayer()` is `null` for the console. Not fired when `regions.yml` cannot be saved.	The region stays and nothing is saved.
`BypassToggleEvent`	A player runs `/vanishregion toggle`, just before the bypass changes. Not fired when the plugin turns a bypass off because the player lost `vanishregion.toggle`.	The bypass keeps its state and nobody's visibility is refreshed.

Notification events fire after the fact. They cannot be cancelled.

Event	Fired when	Thread
`VisibilityRefreshEvent`	One player's visibility was re-evaluated against everyone online and applied to the clients, including after a bypass dropped because `vanishregion.toggle` was taken away.	Main

Listen like any Bukkit event:

@EventHandler
public void on(RegionCreateEvent event) {
    // read the payload; cancellable events support event.setCancelled(true)
}

VisibilityRefreshEvent carries the player's unique id through getPlayerId(). Not every firing changes an answer, so re-ask isHiddenFrom for the pairs you care about.

Event payloads are read-only. Cancellation is the only change a listener can make.

Query service

Every method reads in-memory state. Call them on the main thread. None of them throws.

Method	Returns	Notes
`isHiddenFrom(Player viewer, Player target)`	`boolean`	Whether the target's body is hidden from the viewer. `false` for `null`, the same player, an untracked player or an inactive packet layer.
`isBypassing(UUID player)`	`boolean`	Whether the player turned the personal bypass on. It lives in memory only.
`isInVanishRegion(Player player)`	`boolean`	Whether the player stands in an internal region or a WorldGuard region whose flag is `allow`.
`getRegions()`	`List<RegionView>`	Every internal region, ordered by name. An immutable snapshot.
`getRegion(String name)`	`RegionView`	The internal region with that name, ignoring case, or `null`.
`getRegionsAt(Location location)`	`List<RegionView>`	Every internal region that contains the block of the location. Regions may overlap.
`getApiVersion()`	`String`	The version of the API contract.

RegionView is an immutable record with name, worldName, minX, minY, minZ, maxX, maxY and maxZ. The bounds are inclusive block coordinates. WorldGuard regions are not represented.

Vanish is applied at the packet level. Player#canSee stays true for every pair, so use isHiddenFrom to ask whether a body is hidden, for example to remove a floating nametag.

SnVanishRegionProvider.isAvailable() answers whether the service is currently registered.

Versioning

Call getApiVersion() for the API contract version. It is independent of the plugin version. Additions bump the minor component. Existing members are never removed or changed; deprecated members keep working.