# API Reference The Barrier-API module provides a public interface for other plugins to interact with Barrier's world border system. This page covers all API classes, events, and integration instructions. --- ## Maven / Gradle Setup Barrier-API is available through JitPack. Add the following to your build configuration to depend on the API. ### Maven ```xml <repositories> <repository> <id>jitpack.io</id> <url>https://jitpack.io</url> </repository> </repositories> <dependencies> <dependency> <groupId>com.github.Lodestones</groupId> <artifactId>Barrier-API</artifactId> <version>1.0.34</version> <scope>provided</scope> </dependency> </dependencies> ``` ### Gradle (Kotlin DSL) ```kotlin repositories { maven("https://jitpack.io") } dependencies { compileOnly("com.github.Lodestones:Barrier-API:1.0.34") } ``` ### Gradle (Groovy DSL) ```groovy repositories { maven { url 'https://jitpack.io' } } dependencies { compileOnly 'com.github.Lodestones:Barrier-API:1.0.34' } ``` --- ## Getting the API Instance The static `BarrierAPI` class provides access to the `IBarrierAPI` instance set by the Barrier plugin at startup. ```java import gg.lode.barrierapi.BarrierAPI; import gg.lode.barrierapi.IBarrierAPI; import gg.lode.barrierapi.IStorm; IBarrierAPI api = BarrierAPI.getApi(); IStorm storm = api.getStorm(world); ``` Ensure Barrier is loaded before accessing the API. Add `Barrier` to your `plugin.yml` as a `depend` or `softdepend`. ```yaml softdepend: - Barrier ``` --- ## Core Interfaces ### BarrierAPI Static accessor class for the API singleton. | Method | Return Type | Description | |---|---|---| | `BarrierAPI.getApi()` | `IBarrierAPI` | Retrieve the API instance. Returns `null` if Barrier is not loaded. | ### IBarrierAPI Primary API interface. One method is exposed. | Method | Return Type | Description | |---|---|---| | `getStorm(World world)` | `IStorm` | Get the storm (world border) instance for the specified world. | --- ## IStorm Interface The `IStorm` interface provides full control over a world's border. Below is a categorized reference of all available methods. ### Damage | Method | Return Type | Description | |---|---|---| | `getDamage()` | `double` | Get the damage dealt per tick. | | `setDamage(double damage)` | `void` | Set the damage dealt per tick. | | `getDamageTick()` | `int` | Get the tick interval between damage applications. | | `setDamageTick(int damageTick)` | `void` | Set the tick interval between damage applications. | | `getTicksBeforeDamage()` | `int` | Get the grace period (in ticks) before damage starts after entering the storm. | | `setTicksBeforeDamage(int ticks)` | `void` | Set the grace period before damage starts. | | `damage(Player player)` | `void` | Manually apply storm damage to a player. | ### Position | Method | Return Type | Description | |---|---|---| | `getCurrentX()` | `double` | Get the current X center coordinate. | | `getCurrentZ()` | `double` | Get the current Z center coordinate. | | `getCurrentY()` | `double` | Get the current Y center coordinate. | | `getTargetX()` | `double` | Get the target X coordinate (if moving). | | `getTargetZ()` | `double` | Get the target Z coordinate (if moving). | | `getTargetY()` | `double` | Get the target Y coordinate (if moving). | | `getCurrentCenter()` | `Location` | Get the current center as a Bukkit Location. | | `getTargetCenter()` | `Location` | Get the target center as a Bukkit Location. | | `setOrigin(double x, double z)` | `void` | Set the center immediately (XZ only). | | `setOrigin(double x, double z, int time)` | `void` | Move the center over time (XZ only). | | `setOrigin(double x, double y, double z)` | `void` | Set the center immediately (XYZ). | | `setOrigin(double x, double y, double z, int time)` | `void` | Move the center over time (XYZ). | | `setX(double x)` | `void` | Set the X coordinate immediately. | | `setY(double y)` | `void` | Set the Y coordinate immediately. | | `setZ(double z)` | `void` | Set the Z coordinate immediately. | ### Size — Circle (Radius) | Method | Return Type | Description | |---|---|---| | `getCurrentRadius()` | `double` | Get the current radius. | | `getTargetRadius()` | `double` | Get the target radius (if resizing). | | `setRadius(double radius)` | `void` | Set radius immediately. | | `setRadius(int radius)` | `void` | Set radius immediately (int overload). | | `setRadius(double radius, int time)` | `void` | Resize radius over time (seconds). | ### Size — Square / Square Boxed | Method | Return Type | Description | |---|---|---| | `getCurrentWidth()` | `double` | Get current width. | | `getTargetWidth()` | `double` | Get target width. | | `setWidth(double width)` | `void` | Set width immediately. | | `setWidth(double width, int time)` | `void` | Resize width over time. | | `getCurrentLength()` | `double` | Get current length. | | `getTargetLength()` | `double` | Get target length. | | `setLength(double length)` | `void` | Set length immediately. | | `setLength(double length, int time)` | `void` | Resize length over time. | | `getCurrentHeight()` | `double` | Get current height. | | `getTargetHeight()` | `double` | Get target height. | | `setHeight(double height)` | `void` | Set height immediately. | | `setHeight(double height, int time)` | `void` | Resize height over time. | ### Size — Bulk | Method | Return Type | Description | |---|---|---| | `setSize(double size)` | `void` | Set all dimensions to the same value. | | `setSize(double size, int time)` | `void` | Set all dimensions over time. | | `setSize(double width, double length)` | `void` | Set width and length. | | `setSize(double width, double length, int time)` | `void` | Set width and length over time. | | `setSize(double width, double height, double length)` | `void` | Set all three dimensions. | | `setSize(double width, double height, double length, int time)` | `void` | Set all three dimensions over time. | ### Movement Helpers | Method | Return Type | Description | |---|---|---| | `moveUp(double value)` | `void` | Move center up by value blocks. | | `moveUp(double value, int time)` | `void` | Move center up over time. | | `moveDown(double value)` | `void` | Move center down by value blocks. | | `moveDown(double value, int time)` | `void` | Move center down over time. | | `moveTo(Location location)` | `void` | Move center to a location. | | `moveTo(Location location, int time)` | `void` | Move center to a location over time. | ### Size Helpers | Method | Return Type | Description | |---|---|---| | `shrink(double value)` | `void` | Shrink radius by value. Circle only. | | `shrink(double value, int time)` | `void` | Shrink radius over time. Circle only. | | `expand(double value)` | `void` | Expand radius by value. Circle only. | | `expand(double value, int time)` | `void` | Expand radius over time. Circle only. | | `shrinkArea(double value)` | `void` | Shrink width and length by value. | | `shrinkArea(double value, int time)` | `void` | Shrink width and length over time. | | `expandArea(double value)` | `void` | Expand width and length by value. | | `expandArea(double value, int time)` | `void` | Expand width and length over time. | | `shrinkHeight(double value)` | `void` | Shrink height by value. | | `shrinkHeight(double value, int time)` | `void` | Shrink height over time. | | `expandHeight(double value)` | `void` | Expand height by value. | | `expandHeight(double value, int time)` | `void` | Expand height over time. | ### Control | Method | Return Type | Description | |---|---|---| | `stop()` | `void` | Stop all movement and resizing. | | `stopMoving()` | `void` | Stop movement only. | | `stopResizing()` | `void` | Stop resizing only. | | `isMoving()` | `boolean` | Check if the border is currently moving. | | `isResizing()` | `boolean` | Check if the border is currently resizing. | ### Display | Method | Return Type | Description | |---|---|---| | `getColor()` | `Color` | Get the current border color. | | `setColor(Color color)` | `void` | Set the border color. | | `hideStorm(Player player)` | `void` | Hide the border from a specific player. | | `showStorm(Player player)` | `void` | Show the border to a specific player. | ### Type | Method | Return Type | Description | |---|---|---| | `getStormType()` | `StormType` | Get the current border type. | | `setStormType(StormType type)` | `void` | Change the border type. | ### Timing | Method | Return Type | Description | |---|---|---| | `getTicksToMove()` | `int` | Get remaining ticks until movement completes. | | `setTicksToMove(int time)` | `void` | Set remaining movement ticks. | | `getTicksToShrink()` | `int` | Get remaining ticks until resizing completes. | | `setTicksToShrink(int time)` | `void` | Set remaining resize ticks. | | `update()` | `void` | Force a manual border update/refresh. | ### Query | Method | Return Type | Description | |---|---|---| | `isInStorm(Entity entity)` | `boolean` | Check if an entity is currently inside the storm. | --- ## StormType Enum The `StormType` enum defines the three available border shapes. | Value | Description | |---|---| | `CIRCLE` | A circular border on the XZ plane. Controlled by radius. Has no height component. | | `SQUARE` | A square border on the XZ plane. Controlled by width and length. Has no height component. | | `SQUARE_BOXED` | A 3D box border. Controlled by width, length, and height. Supports vertical boundaries. | --- ## Events Barrier fires three custom Bukkit events. ### PlayerEnterStormEvent Fired when a player enters the storm area. | Method | Return Type | Description | |---|---|---| | `getPlayer()` | `Player` | The player who entered the storm. | | `getWorld()` | `World` | The world the storm belongs to. | | `getTicksBeforeDamage()` | `int` | Grace period ticks before damage begins. | | `setTicksBeforeDamage(int ticks)` | `void` | Modify the grace period. | | `isInvulnerable()` | `boolean` | Whether the player is invulnerable. | ### PlayerLeaveStormEvent Fired when a player leaves the storm area. | Method | Return Type | Description | |---|---|---| | `getPlayer()` | `Player` | The player who left the storm. | | `getWorld()` | `World` | The world the storm belongs to. | ### PlayerDamageByStormEvent Fired when a player takes damage from the storm. Implements `Cancellable`. | Method | Return Type | Description | |---|---|---| | `getPlayer()` | `Player` | The player taking damage. | | `getDamage()` | `double` | The damage amount. | | `setDamage(int damage)` | `void` | Modify the damage amount. | | `isCancelled()` | `boolean` | Whether the event is cancelled. | | `setCancelled(boolean cancelled)` | `void` | Cancel or uncancel the event. | ### Example: Listening to Events ```java import gg.lode.barrierapi.event.PlayerEnterStormEvent; import gg.lode.barrierapi.event.PlayerDamageByStormEvent; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; public class StormListener implements Listener { @EventHandler public void onEnterStorm(PlayerEnterStormEvent event) { event.getPlayer().sendMessage("You have entered the storm!"); event.setTicksBeforeDamage(60); // 3-second grace period } @EventHandler public void onStormDamage(PlayerDamageByStormEvent event) { if (event.getPlayer().hasPermission("barrier.immune")) { event.setCancelled(true); } } } ``` --- ## Example: Programmatic Border Control ```java import gg.lode.barrierapi.BarrierAPI; import gg.lode.barrierapi.IStorm; import gg.lode.barrierapi.StormType; import org.bukkit.Bukkit; import org.bukkit.Color; import org.bukkit.World; public class BorderManager { public void setupBorder() { World world = Bukkit.getWorld("world"); IStorm storm = BarrierAPI.getApi().getStorm(world); // Set to circle type with radius 500 storm.setStormType(StormType.CIRCLE); storm.setRadius(500); // Configure damage storm.setDamage(1.0); storm.setDamageTick(20); // Every second // Set color to red storm.setColor(Color.fromRGB(0xFF0000)); // Shrink to radius 50 over 5 minutes (300 seconds) storm.setRadius(50, 300); } } ``` --- ## Related Pages - [[Barrier/Developers/Overview]] — developer architecture and build instructions - [[Lead/Server Owners/Commands]] — command reference for server owners