Skip to content

Commit 54c9f67

Browse files
ez-pluginsez-plugins
committed
docs: rewrite developer API documentation
- Maven and Gradle dependency snippets with correct artifact coordinates - plugin.yml depend/softdepend examples - Full method reference: isAvailable(), rtpPlayer() overloads, getTeleportService() - TeleportReason enum table (COMMAND vs JOIN) - TeleportService interface shown in full - RandomTeleportSettings YAML key reference table with types and examples - Null-safety guidance for soft dependencies - Worked example combining custom settings, biome filter, and success callback
1 parent 320ee41 commit 54c9f67

1 file changed

Lines changed: 204 additions & 25 deletions

File tree

‎docs/api/plugin-api.md‎

Lines changed: 204 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,237 @@
1-
# EzRTP Plugin API
1+
---
2+
title: Developer API
3+
nav_order: 10
4+
---
25

3-
Purpose: Expose a small helper API for other plugins to trigger random teleports (RTP) programmatically.
6+
# Developer API
47

5-
Usage:
8+
EzRTP exposes a small public API so other plugins can trigger random teleports
9+
programmatically — including custom destinations, radius overrides, and
10+
success/failure callbacks.
611

7-
- Simple RTP: Calls the plugin's default RTP flow (uses configured settings, costs, cooldowns, etc.)
12+
---
813

9-
Example:
14+
## Adding the dependency
15+
16+
The API is published as a separate lightweight artifact (`ezrtp-api`) that
17+
contains only the classes you need. You do **not** need to depend on the full
18+
plugin jar.
19+
20+
### Maven
21+
22+
```xml
23+
<dependency>
24+
<groupId>com.skyblockexp</groupId>
25+
<artifactId>ezrtp-api</artifactId>
26+
<version>3.0.1</version>
27+
<scope>provided</scope>
28+
</dependency>
29+
```
30+
31+
### Gradle
32+
33+
```groovy
34+
compileOnly 'com.skyblockexp:ezrtp-api:3.0.1'
35+
```
36+
37+
Declare EzRTP as a soft or hard dependency in your `plugin.yml` so Bukkit
38+
loads it before your plugin:
39+
40+
```yml
41+
# hard dependency — your plugin will not load if EzRTP is absent
42+
depend: [EzRTP]
43+
44+
# soft dependency — your plugin loads with or without EzRTP
45+
softdepend: [EzRTP]
46+
```
47+
48+
---
49+
50+
## Quick start
1051
1152
```java
1253
import com.skyblockexp.ezrtp.api.EzRtpAPI;
1354

14-
// RTP with default settings
55+
// Check that EzRTP is running before calling anything
56+
if (EzRtpAPI.isAvailable()) {
57+
EzRtpAPI.rtpPlayer(player);
58+
}
59+
```
60+
61+
That's it for the simplest case. The teleport uses all settings from the
62+
server's `rtp.yml`, charges any configured cost, and respects cooldowns.
63+
64+
---
65+
66+
## API reference
67+
68+
All methods are static on `EzRtpAPI`.
69+
70+
### `isAvailable()`
71+
72+
```java
73+
boolean available = EzRtpAPI.isAvailable();
74+
```
75+
76+
Returns `true` if EzRTP is loaded and its service is registered. Call this
77+
before any other method if EzRTP is a soft dependency.
78+
79+
---
80+
81+
### `rtpPlayer(Player player)`
82+
83+
Teleport a player using the server's default RTP settings.
84+
85+
```java
1586
EzRtpAPI.rtpPlayer(player);
1687
```
1788

18-
- RTP with custom settings: Use an instance of `RandomTeleportSettings`.
89+
- Uses `TeleportReason.COMMAND` — cooldowns, costs, and limits apply normally.
90+
- Fire-and-forget. No way to know if it succeeded.
1991

20-
Example:
92+
---
93+
94+
### `rtpPlayer(Player player, Object settings)`
95+
96+
Teleport with custom settings (e.g. a different world or radius).
2197

2298
```java
23-
import com.skyblockexp.ezrtp.api.EzRtpAPI;
2499
import com.skyblockexp.ezrtp.config.RandomTeleportSettings;
100+
import org.bukkit.configuration.file.YamlConfiguration;
101+
102+
YamlConfiguration cfg = new YamlConfiguration();
103+
cfg.set("world", "world_the_end");
104+
cfg.set("radius.min", 1000);
105+
cfg.set("radius.max", 5000);
25106

26-
RandomTeleportSettings settings = ...; // build or obtain from config
107+
RandomTeleportSettings settings = RandomTeleportSettings.fromConfiguration(cfg, getLogger());
108+
EzRtpAPI.rtpPlayer(player, settings);
109+
```
110+
111+
`RandomTeleportSettings.fromConfiguration()` reads a `ConfigurationSection`
112+
exactly like EzRTP reads `rtp.yml`. Any key you omit uses the built-in default.
113+
114+
---
115+
116+
### `rtpPlayer(Player player, Object settings, Consumer<Boolean> callback)`
117+
118+
Teleport with custom settings **and** a callback that fires when the teleport
119+
completes or fails.
120+
121+
```java
27122
EzRtpAPI.rtpPlayer(player, settings, success -> {
28123
if (success) {
29-
// do something on success
124+
player.sendMessage("You were teleported!");
125+
} else {
126+
player.sendMessage("No safe location found.");
30127
}
31128
});
32129
```
33130

34-
Notes:
35-
36-
- If EzRTP is not present or not enabled, the API will log a warning and the call will be ignored.
37-
- The API helpers default to using `TeleportReason.COMMAND` for cost/cooldown resolution.
131+
The `Boolean` passed to the callback is:
132+
- `true` — teleport completed successfully.
133+
- `false` — teleport failed (no valid location found, player moved during countdown, etc.).
38134

39-
Where to find the code:
135+
The callback is invoked on the main server thread.
40136

41-
- API helper: [ezrtp-common/src/main/java/com/skyblockexp/ezrtp/api/EzRtpAPI.java](ezrtp-common/src/main/java/com/skyblockexp/ezrtp/api/EzRtpAPI.java#L1-L200)
42-
- Plugin accessor: [ezrtp-common/src/main/java/com/skyblockexp/ezrtp/EzRtpPlugin.java](ezrtp-common/src/main/java/com/skyblockexp/ezrtp/EzRtpPlugin.java#L1-L200)
137+
---
43138

44-
This repository includes a lightweight API helper designed for ease-of-use by other plugins. It does not introduce a formal service registry; instead it locates the running EzRTP plugin via the server plugin manager and delegates to the running `RandomTeleportService`.
139+
### `getTeleportService()`
45140

46-
If you need a more advanced integration (for example, to run teleports using a specific teleport reason, or to integrate with economy providers in a custom way), obtain the `RandomTeleportService` directly:
141+
Returns the raw `TeleportService` instance for advanced use cases.
47142

48143
```java
49-
import com.skyblockexp.ezrtp.api.EzRtpAPI;
50-
import com.skyblockexp.ezrtp.teleport.RandomTeleportService;
144+
import com.skyblockexp.ezrtp.api.TeleportService;
145+
import com.skyblockexp.ezrtp.teleport.TeleportReason;
51146

52-
RandomTeleportService service = EzRtpAPI.getTeleportService();
147+
TeleportService service = EzRtpAPI.getTeleportService();
53148
if (service != null) {
54-
// call service.teleportPlayer(...) variants directly
149+
service.teleportPlayer(player, TeleportReason.JOIN);
150+
}
151+
```
152+
153+
Use this when you need to pass a specific `TeleportReason` or call a variant
154+
not exposed by the static helpers.
155+
156+
---
157+
158+
## `TeleportReason` enum
159+
160+
`TeleportReason` tells EzRTP why the teleport is happening. This affects which
161+
cost and cooldown rules are applied.
162+
163+
| Value | When to use |
164+
|:------|:------------|
165+
| `COMMAND` | Player triggered the teleport via a command or button. Cooldowns and costs apply. |
166+
| `JOIN` | Player joined the server and was auto-teleported. Uses the `on-join` cost/cooldown rules. |
167+
168+
---
169+
170+
## `TeleportService` interface
171+
172+
The full interface for advanced callers:
173+
174+
```java
175+
public interface TeleportService {
176+
// Simple teleport, no callback
177+
void teleportPlayer(Player player, TeleportReason reason);
178+
179+
// Custom settings, no callback
180+
void teleportPlayer(Player player, Object settings, TeleportReason reason);
181+
182+
// Simple teleport with callback
183+
void teleportPlayer(Player player, TeleportReason reason, Consumer<Boolean> callback);
184+
185+
// Custom settings with callback
186+
void teleportPlayer(Player player, Object settings, TeleportReason reason, Consumer<Boolean> callback);
55187
}
56188
```
57189

58-
The API is intentionally minimal to avoid tight coupling; it is safe to call from other plugins during runtime, but callers should handle the case where EzRTP is not present or not yet enabled.
190+
---
191+
192+
## `RandomTeleportSettings` — full YAML reference
193+
194+
`RandomTeleportSettings.fromConfiguration(ConfigurationSection, Logger)` reads
195+
any YAML section. Below are the keys you can set:
196+
197+
| Key | Type | Example | Description |
198+
|:----|:-----|:--------|:------------|
199+
| `world` | String | `world_the_end` | World to teleport into. `auto` = player's current world. |
200+
| `center.x` / `center.z` | int | `0` | Search centre coordinates. |
201+
| `radius.min` | int | `500` | Minimum distance from centre. |
202+
| `radius.max` | int | `3000` | Maximum distance from centre. |
203+
| `radius.use-world-border` | bool | `true` | Use world border edge as the maximum radius. |
204+
| `min-y` / `max-y` | int | `54` / `320` | Vertical bounds for destinations. |
205+
| `max-attempts` | int | `20` | Candidate attempts before failing. |
206+
| `cost` | double | `5.0` | Economy cost per teleport (Vault). |
207+
| `countdown-seconds` | int | `3` | Countdown before teleport. `0` = instant. |
208+
| `search-pattern` | String | `circle` | Coordinate search shape. See [Search Patterns](../config/search-patterns). |
209+
| `biomes.include` | list | `[FOREST, PLAINS]` | Require one of these biomes. |
210+
| `biomes.exclude` | list | `[OCEAN]` | Reject these biomes. |
211+
| `protection.avoid-claims` | bool | `true` | Skip locations inside protected claims. |
212+
213+
```java
214+
YamlConfiguration cfg = new YamlConfiguration();
215+
cfg.set("world", "world");
216+
cfg.set("radius.min", 2000);
217+
cfg.set("radius.max", 8000);
218+
cfg.set("search-pattern", "circle");
219+
cfg.set("biomes.include", List.of("FOREST", "BIRCH_FOREST"));
220+
cfg.set("cost", 10.0);
221+
222+
RandomTeleportSettings settings = RandomTeleportSettings.fromConfiguration(cfg, getLogger());
223+
EzRtpAPI.rtpPlayer(player, settings, success -> {
224+
if (!success) player.sendMessage("Could not find a forest location. Try again.");
225+
});
226+
```
227+
228+
---
229+
230+
## Null safety
231+
232+
- If EzRTP is not installed or not yet enabled, `getTeleportService()` returns
233+
`null` and all `rtpPlayer` helpers silently do nothing (or invoke the callback
234+
with `false`).
235+
- Always guard with `EzRtpAPI.isAvailable()` when EzRTP is a soft dependency.
236+
- The API is safe to call from any thread; EzRTP handles its own async/sync
237+
boundaries internally.

0 commit comments

Comments
 (0)