105 lines
2.6 KiB
Markdown
105 lines
2.6 KiB
Markdown
# 🗺️ Regions – Lightweight Region Library for Bukkit
|
||
|
||
**Regions** is a lightweight and simple **Java library** for Bukkit/Spigot plugins. It helps you define 3D rectangular regions and automatically detects when players **enter or leave** them.
|
||
|
||
Use it as a dependency in your own plugins to easily add region logic.
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- ✅ Define rectangular cuboid regions with two `Location`s
|
||
- 🚶 Detect when a player **enters** or **exits** a region
|
||
- 🧰 Easy API to add, remove, and query regions
|
||
- 🔄 Registerable event listeners
|
||
- 🧩 Built for plugin developers – plug and play
|
||
|
||
---
|
||
|
||
## 🔧 Getting Started
|
||
|
||
### 1. Create a Region
|
||
|
||
First, create two `Location` points and then create a region between them:
|
||
|
||
```java
|
||
Location loc1 = new Location(Bukkit.getWorld("<World Name>"), x1, y1, z1);
|
||
Location loc2 = new Location(Bukkit.getWorld("<World Name>"), x2, y2, z2);
|
||
|
||
RegionData region = new RegionData("<Region Name>", loc1, loc2);
|
||
Regions.addRegion(region);
|
||
```
|
||
|
||
### 2. Register the Event Listener
|
||
|
||
Call this once (e.g. in your plugin's `onEnable`) to enable automatic region tracking:
|
||
|
||
```java
|
||
public void onEnable() {
|
||
Regions.registerListener(this); // 'this' is your plugin instance
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📡 Region Events
|
||
|
||
These are custom events that you can listen for:
|
||
|
||
```java
|
||
@EventHandler
|
||
public void onRegionEnter(PlayerEnterRegionEvent event) {
|
||
Player player = event.getPlayer();
|
||
RegionData region = event.getRegion();
|
||
player.sendMessage("Entered region: " + region.getName());
|
||
}
|
||
|
||
@EventHandler
|
||
public void onRegionExit(PlayerExitRegionEvent event) {
|
||
Player player = event.getPlayer();
|
||
RegionData region = event.getRegion();
|
||
player.sendMessage("Left region: " + region.getName());
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 API Reference
|
||
|
||
```java
|
||
Regions.addRegion(RegionData region); // Add a region
|
||
Regions.deleteRegion(RegionData region); // Remove a region
|
||
|
||
Regions.getRegions(); // Get all regions
|
||
Regions.getRegionsByName("Spawn"); // Get regions by name
|
||
|
||
Regions.getRegionInLocation(Location loc); // First region that contains loc
|
||
Regions.getRegionsInLocation(Location loc); // All regions that contain loc
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Integration in Your Plugin
|
||
|
||
Simply include the compiled `Regions-1.0.jar` as a library in your plugin project. Then:
|
||
|
||
1. Register the movement listener:
|
||
```java
|
||
Regions.registerListener(this);
|
||
```
|
||
2. Add or query regions as needed.
|
||
3. Listen for `PlayerEnterRegionEvent` and `PlayerExitRegionEvent`.
|
||
|
||
---
|
||
|
||
## 🧑💻 Author
|
||
|
||
Created by **Jernej T.**
|
||
Pull requests and contributions are welcome!
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT – do whatever you want, just give credit.
|