Skip to content

Commit f208de2

Browse files
rossnoahrossnoah
committed
some random things
1 parent 676f33a commit f208de2

8 files changed

Lines changed: 497 additions & 195 deletions

File tree

‎API.md‎

Lines changed: 248 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,268 @@
1-
# PerPlayerKit API
1+
# PerPlayerKit API Documentation
22

3-
The PerPlayerKit API is a simple Java API that allows developers to interact with the plugin. The API is **NOT** stable and will possibly change in the future.
3+
## Overview
44

5-
### Example Usage:
5+
The PerPlayerKit API provides a comprehensive, modern interface for interacting with the PerPlayerKit plugin. It features:
66

7-
Add plugin jar to `./lib` folder in your project.
7+
- **Thread-safe operations** - All API methods can be safely called from any thread
8+
- **Async/await patterns** - CompletableFuture-based operations for non-blocking execution
9+
- **Fluent builders** - Chainable method calls for complex operations
10+
- **Backwards compatibility** - Seamless integration with existing code
11+
- **Modern Java patterns** - Uses Optional, Stream API, and other Java 8+ features
812

9-
Add to pom.xml:
13+
## Getting Started
1014

15+
### Basic Usage
16+
17+
```java
18+
// Get the API instance
19+
PerPlayerKitAPI api = PerPlayerKitAPI.getInstance();
20+
21+
// Check if PerPlayerKit is available
22+
if (!PerPlayerKitAPI.isAvailable()) {
23+
getLogger().warning("PerPlayerKit is not available!");
24+
return;
25+
}
26+
27+
// Register your plugin (recommended for better support)
28+
APIRegistration registration = api.registerPlugin(this);
1129
```
12-
<dependency>
13-
<groupId>com.local</groupId>
14-
<artifactId>PerPlayerKit</artifactId>
15-
<version>local</version>
16-
<scope>system</scope>
17-
<systemPath>${project.basedir}/lib/PerPlayerKit-1.1.jar</systemPath>
18-
</dependency>
30+
31+
### Kit Management
32+
33+
```java
34+
// Save player's current inventory to slot 1
35+
api.kits()
36+
.forPlayer(player)
37+
.saveCurrentInventory(1)
38+
.thenRun(() -> player.sendMessage("Kit saved!"));
39+
40+
// Load a kit for a player
41+
api.kits()
42+
.forPlayer(player)
43+
.loadKit(1)
44+
.thenAccept(success -> {
45+
if (success) {
46+
player.sendMessage("Kit loaded!");
47+
} else {
48+
player.sendMessage("No kit found in slot 1");
49+
}
50+
});
51+
52+
// Check if player has a kit
53+
if (api.kits().forPlayer(player).hasKit(1)) {
54+
player.sendMessage("You have a kit in slot 1");
55+
}
56+
57+
// Get all occupied slots
58+
List<Integer> slots = api.kits().forPlayer(player).getOccupiedSlots();
59+
player.sendMessage("You have kits in slots: " + slots);
1960
```
2061

62+
### Advanced Kit Operations
63+
2164
```java
22-
import dev.noah.perplayerkit.API;
23-
import dev.noah.perplayerkit.PublicKit;
24-
// other imports etc
65+
// Use the advanced builder pattern
66+
api.kits()
67+
.builder()
68+
.forPlayer(player)
69+
.inSlot(2)
70+
.withItems(customItems)
71+
.withValidation(true)
72+
.withNotification(true)
73+
.save()
74+
.thenRun(() -> getLogger().info("Kit saved with validation"));
2575

26-
public class ExamplePlugin extends JavaPlugin {
76+
// Copy a kit to another slot
77+
api.kits()
78+
.forPlayer(player)
79+
.copyKit(1, 2)
80+
.thenRun(() -> player.sendMessage("Kit copied from slot 1 to slot 2"));
2781

28-
public void onEnable() {
29-
// On enable code...
82+
// Swap two kits
83+
api.kits()
84+
.forPlayer(player)
85+
.swapKits(1, 2)
86+
.thenRun(() -> player.sendMessage("Kits swapped"));
87+
```
88+
89+
### Player Management
90+
91+
```java
92+
// Check player permissions
93+
PlayerAPI players = api.players();
94+
if (players.hasKitPermission(player, 5)) {
95+
player.sendMessage("You can use kit slot 5");
96+
}
97+
98+
// Get accessible slots
99+
List<Integer> accessibleSlots = players.getAccessibleSlots(player);
100+
player.sendMessage("You can access slots: " + accessibleSlots);
101+
102+
// Get player statistics
103+
players.getStatistics(player.getUniqueId())
104+
.thenAccept(stats -> {
105+
player.sendMessage("Kits saved: " + stats.getKitsSaved());
106+
player.sendMessage("Kits loaded: " + stats.getKitsLoaded());
107+
});
108+
109+
// Manage preferences
110+
players.setAutoSaveEnabled(player, true);
111+
players.setGuiSoundsEnabled(player, false);
112+
players.setPreferredGuiTheme(player, "dark");
113+
```
114+
115+
### Event Handling
116+
117+
```java
118+
// Listen to kit events
119+
PerPlayerKitEventManager events = api.events();
120+
121+
// Kit saved event
122+
events.onKitSaved(event -> {
123+
Player p = event.getPlayer();
124+
int slot = event.getSlot();
125+
getLogger().info(p.getName() + " saved kit in slot " + slot);
126+
});
127+
128+
// Kit loading event (cancellable)
129+
events.onKitLoading(EventPriority.HIGH, event -> {
130+
if (event.getPlayer().getName().equals("BlockedPlayer")) {
131+
event.setCancelled(true);
132+
event.getPlayer().sendMessage("You cannot load kits!");
30133
}
134+
});
135+
```
136+
137+
### GUI Management
31138

139+
```java
140+
// Open GUIs
141+
GuiAPI gui = api.gui();
142+
gui.openMainGui(player);
143+
gui.openMainGui(player, "dark"); // With specific theme
144+
gui.openKitPreview(player, 1); // Preview kit slot 1
145+
146+
// Create custom GUI
147+
gui.builder()
148+
.title("Custom Kit Menu")
149+
.size(27)
150+
.theme("neon")
151+
.item(13, customItem, context -> {
152+
context.getPlayer().sendMessage("Clicked!");
153+
})
154+
.build()
155+
.open(player);
156+
```
32157

33-
// Give a player a public kit when they join the server
34-
@EventHandler
35-
public void onPlayerJoin(PlayerJoinEvent e) {
36-
// Get the API instance
37-
API api = API.getInstance();
158+
### Data Management
38159

39-
// Get a list of all public kits
40-
List<PublicKit> publicKits = api.getPublicKits();
160+
```java
161+
// Store custom data
162+
PlayerDataAPI data = api.data();
163+
data.setData(player.getUniqueId(), "custom.score", 100)
164+
.thenRun(() -> getLogger().info("Score saved"));
41165

42-
// Load a public kit
43-
api.loadPublicKit(e.getPlayer(), publicKits.get(0));
166+
// Retrieve data with type safety
167+
data.getData(player.getUniqueId(), "custom.score", Integer.class)
168+
.thenAccept(score -> {
169+
if (score.isPresent()) {
170+
player.sendMessage("Your score: " + score.get());
171+
}
172+
});
173+
```
174+
175+
## API Interfaces
176+
177+
### Core Interfaces
178+
179+
- **`PerPlayerKitAPI`** - Main entry point providing access to all functionality
180+
- **`KitAPI`** - Kit management operations with fluent builders
181+
- **`PlayerAPI`** - Player permissions, statistics, and preferences
182+
- **`GuiAPI`** - GUI management and custom GUI creation
183+
- **`PlayerDataAPI`** - Persistent data storage and retrieval
184+
- **`PerPlayerKitEventManager`** - Event system with modern listeners
185+
186+
### Builder Patterns
187+
188+
All major operations support fluent builder patterns:
189+
190+
- **`PlayerKitBuilder`** - Player-specific kit operations
191+
- **`KitBuilder`** - Advanced kit creation and management
192+
- **`PlayerBuilder`** - Player preference management
193+
- **`GuiBuilder`** - Custom GUI creation
194+
- **`DataBuilder`** - Batch data operations
195+
196+
## Error Handling
197+
198+
```java
199+
// CompletableFuture error handling
200+
api.kits().saveKit(playerId, slot, items)
201+
.thenRun(() -> getLogger().info("Kit saved successfully"))
202+
.exceptionally(throwable -> {
203+
getLogger().severe("Failed to save kit: " + throwable.getMessage());
204+
return null;
205+
});
206+
```
207+
208+
## Thread Safety
209+
210+
All API operations are thread-safe and can be called from any thread:
211+
212+
```java
213+
// Safe to call from any thread
214+
Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
215+
api.kits().saveKit(playerId, slot, items)
216+
.thenRun(() -> getLogger().info("Kit saved asynchronously"));
217+
});
218+
```
219+
220+
## Best Practices
221+
222+
### 1. Register Your Plugin
223+
```java
224+
@Override
225+
public void onEnable() {
226+
if (PerPlayerKitAPI.isAvailable()) {
227+
APIRegistration registration = PerPlayerKitAPI.getInstance().registerPlugin(this);
44228
}
229+
}
230+
```
231+
232+
### 2. Handle Async Operations Properly
233+
```java
234+
// Good: Chain operations
235+
api.kits().saveKit(playerId, slot, items)
236+
.thenCompose(v -> api.players().getStatistics(playerId))
237+
.thenAccept(stats -> updatePlayerDisplay(stats));
238+
```
45239

240+
### 3. Validate Player Permissions
241+
```java
242+
if (!api.players().hasKitPermission(player, slot)) {
243+
player.sendMessage("You don't have permission to use this kit slot!");
244+
return;
46245
}
47246
```
247+
248+
## Version Compatibility
249+
250+
- **API Version**: 2.0.0
251+
- **Minimum Plugin Version**: 1.6.3+
252+
- **Java Version**: 17+
253+
- **Bukkit/Spigot**: 1.17+
254+
255+
## Migration from Legacy API
256+
257+
```java
258+
// Old way (still works for backwards compatibility)
259+
API legacyApi = API.getInstance();
260+
List<PublicKit> publicKits = legacyApi.getPublicKits();
261+
262+
// New way
263+
PerPlayerKitAPI api = PerPlayerKitAPI.getInstance();
264+
api.kits()
265+
.forPlayer(player)
266+
.saveCurrentInventory(1)
267+
.thenRun(() -> player.sendMessage("Kit saved!"));
268+
```

0 commit comments

Comments
 (0)