Skip to content

Commit 510fcd6

Browse files
SuperCraftingSuperCrafting
authored
Merge pull request #1 from SuperCrafting/readme
Update README.md
2 parents 3935a47 + 4adc650 commit 510fcd6

File tree

1 file changed

+316
-0
lines changed

1 file changed

+316
-0
lines changed

‎README.md‎

Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,317 @@
11
# MenuAPI
2+
3+
MenuAPI is a Java library designed for creating and managing interactive and dynamic menus in applications using Minecraft. This API includes advanced features such as pagination, decorators, editors, and interactive items.
4+
5+
## Key Features
6+
7+
- **Pagination**: Efficiently manage large numbers of items with a paging system.
8+
- **Decorators**: Add aesthetic elements to your menus.
9+
- **Editors**: Dynamically modify menu content.
10+
- **Interactive Slots**: Create slots linked to another inventory or interactive items.
11+
12+
## Examples
13+
14+
### Basic Menu Example
15+
16+
A simple menu with a title and rows:
17+
18+
```java
19+
public class SimpleMenu extends Menu {
20+
21+
public SimpleMenu() {
22+
super(Component.text("My Simple Menu"), 3); // 3 rows (27 slots)
23+
}
24+
}
25+
```
26+
27+
To open the menu for a player:
28+
29+
```java
30+
SimpleMenu menu = new SimpleMenu();
31+
menu.open(player);
32+
```
33+
34+
### MenuItem Examples
35+
36+
MenuItem allows you to create interactive items with custom click behaviors.
37+
38+
#### Example 1: Close Button
39+
40+
```java
41+
setSlot(26, new MenuItem(new ItemStack(Material.BARRIER)) {
42+
@Override
43+
public void click(Click click) {
44+
click.player().closeInventory();
45+
}
46+
});
47+
```
48+
49+
#### Example 2: Teleport Button
50+
51+
```java
52+
ItemStack teleportItem = new ItemStack(Material.ENDER_PEARL);
53+
ItemMeta meta = teleportItem.getItemMeta();
54+
meta.displayName(Component.text("Teleport to Spawn"));
55+
teleportItem.setItemMeta(meta);
56+
57+
setSlot(13, new MenuItem(teleportItem) {
58+
@Override
59+
public void click(Click click) {
60+
Player player = click.player();
61+
player.teleport(player.getWorld().getSpawnLocation());
62+
player.sendMessage(Component.text("Teleported to spawn!"));
63+
player.closeInventory();
64+
}
65+
});
66+
```
67+
68+
#### Example 3: Item Giving Button
69+
70+
```java
71+
ItemStack giveItem = new ItemStack(Material.DIAMOND);
72+
ItemMeta meta = giveItem.getItemMeta();
73+
meta.displayName(Component.text("Receive Diamonds"));
74+
giveItem.setItemMeta(meta);
75+
76+
setSlot(14, new MenuItem(giveItem) {
77+
@Override
78+
public void click(Click click) {
79+
Player player = click.player();
80+
player.getInventory().addItem(new ItemStack(Material.DIAMOND, 5));
81+
player.sendMessage(Component.text("You received 5 diamonds!"));
82+
}
83+
});
84+
```
85+
86+
### MenuEditor Example
87+
88+
MenuEditor allows you to dynamically modify menu content. Here's an example of a custom editor that displays player statistics:
89+
90+
```java
91+
public class PlayerStatsEditor implements MenuEditor {
92+
93+
private final Player player;
94+
95+
public PlayerStatsEditor(Player player) {
96+
this.player = player;
97+
}
98+
99+
@Override
100+
public void edit(@NotNull Menu menu, @NotNull Inventory inventory) {
101+
// Create health indicator
102+
ItemStack healthItem = new ItemStack(Material.RED_DYE,
103+
(int) Math.ceil(player.getHealth()));
104+
ItemMeta healthMeta = healthItem.getItemMeta();
105+
healthMeta.displayName(Component.text("Health: " + player.getHealth()));
106+
healthItem.setItemMeta(healthMeta);
107+
inventory.setItem(0, healthItem);
108+
109+
// Create food indicator
110+
ItemStack foodItem = new ItemStack(Material.COOKED_BEEF,
111+
Math.max(1, player.getFoodLevel()));
112+
ItemMeta foodMeta = foodItem.getItemMeta();
113+
foodMeta.displayName(Component.text("Food: " + player.getFoodLevel()));
114+
foodItem.setItemMeta(foodMeta);
115+
inventory.setItem(1, foodItem);
116+
117+
// Create experience indicator
118+
ItemStack expItem = new ItemStack(Material.EXPERIENCE_BOTTLE);
119+
ItemMeta expMeta = expItem.getItemMeta();
120+
expMeta.displayName(Component.text("Level: " + player.getLevel()));
121+
expItem.setItemMeta(expMeta);
122+
inventory.setItem(2, expItem);
123+
}
124+
}
125+
```
126+
127+
Usage in a menu:
128+
129+
```java
130+
public class StatsMenu extends Menu {
131+
132+
public StatsMenu(Player player) {
133+
super(Component.text("Player Stats"), 1);
134+
135+
// Register the custom editor
136+
registerEditor(new PlayerStatsEditor(player));
137+
}
138+
}
139+
```
140+
141+
### MenuPagination Examples
142+
143+
MenuPagination helps manage large collections of items across multiple pages.
144+
145+
#### Example 1: Simple Pagination with Items
146+
147+
```java
148+
public class ItemListMenu extends Menu {
149+
150+
public ItemListMenu(List<ItemStack> items) {
151+
super(Component.text("Item List"), 6);
152+
153+
// Create pagination that fills the entire menu
154+
MenuPagination pagination = MenuPagination.full(this);
155+
156+
// Add all items as forbidden slots (display only)
157+
for (ItemStack item : items) {
158+
pagination.addItem(new ForbiddenSlot(item));
159+
}
160+
161+
// Register the pagination
162+
registerEditor(pagination);
163+
}
164+
}
165+
```
166+
167+
#### Example 2: Middle Pagination (for larger menus)
168+
169+
```java
170+
public class PlayerListMenu extends Menu {
171+
172+
public PlayerListMenu(Collection<Player> players) {
173+
super(Component.text("Online Players"), 6);
174+
175+
// Use middle pagination to leave space for decorations
176+
MenuPagination pagination = MenuPagination.middle(this);
177+
178+
for (Player p : players) {
179+
ItemStack playerHead = new ItemStack(Material.PLAYER_HEAD);
180+
ItemMeta meta = playerHead.getItemMeta();
181+
meta.displayName(Component.text(p.getName()));
182+
playerHead.setItemMeta(meta);
183+
184+
pagination.addItem(new MenuItem(playerHead) {
185+
@Override
186+
public void click(Click click) {
187+
click.player().sendMessage(
188+
Component.text("You clicked on " + p.getName())
189+
);
190+
}
191+
});
192+
}
193+
194+
registerEditor(pagination);
195+
}
196+
}
197+
```
198+
199+
#### Example 3: Custom Pagination Slots
200+
201+
```java
202+
public class CustomPaginationMenu extends Menu {
203+
204+
public CustomPaginationMenu() {
205+
super(Component.text("Custom Layout"), 5);
206+
207+
// Define custom slots for pagination (center area only)
208+
IntList customSlots = IntList.of(
209+
10, 11, 12, 13, 14, 15, 16,
210+
19, 20, 21, 22, 23, 24, 25,
211+
28, 29, 30, 31, 32, 33, 34
212+
);
213+
214+
// Custom page changer at specific positions
215+
MenuPagination pagination = MenuPagination.create(
216+
39, // Previous page button slot
217+
41, // Next page button slot
218+
MenuPagination.PAGE_CHANGER,
219+
customSlots
220+
);
221+
222+
// Add items
223+
for (int i = 0; i < 50; i++) {
224+
ItemStack item = new ItemStack(Material.STONE, i + 1);
225+
pagination.addItem(new ForbiddenSlot(item));
226+
}
227+
228+
registerEditor(pagination);
229+
230+
// Add border decoration
231+
decorate(MenuDecoration.flat(
232+
new ItemStack(Material.GRAY_STAINED_GLASS_PANE)
233+
));
234+
}
235+
}
236+
```
237+
238+
### Complete Example: Menu with All Features
239+
240+
The following example demonstrates a menu utilizing multiple features of the API.
241+
242+
```java
243+
private static class ExampleMenu extends Menu {
244+
245+
public ExampleMenu(Inventory inventory) {
246+
super(Component.text("Example menu"), 5);
247+
248+
// Adding decoration to the menu
249+
decorate(MenuDecoration.flat(new ItemStack(Material.GRAY_STAINED_GLASS_PANE)));
250+
251+
// Setting up pagination
252+
MenuPagination pagination = MenuPagination.full(this);
253+
for (int i = 0; i < 100; i++) {
254+
ItemStack itemStack = new ItemStack(Material.STONE, i + 1);
255+
itemStack.setData(DataComponentTypes.MAX_STACK_SIZE, Math.min(99, i + 1));
256+
pagination.addItem(new ForbiddenSlot(itemStack));
257+
}
258+
registerEditor(pagination);
259+
260+
// Slots linked to another inventory
261+
setSlot(4, new InventorySlot(inventory, 0));
262+
setSlot(5, new InventorySlot(inventory, 1));
263+
264+
// Interactive item
265+
setSlot(9 * 4 - 1, new MenuItem(new ItemStack(Material.BARRIER)) {
266+
@Override
267+
public void click(Click click) {
268+
click.player().closeInventory();
269+
}
270+
});
271+
}
272+
}
273+
```
274+
275+
### Decorators
276+
277+
Decorators allow you to add aesthetic elements to your menus. In the example above, `MenuDecoration.flat` is used to fill menu slots with gray stained glass panes.
278+
279+
```java
280+
decorate(MenuDecoration.flat(new ItemStack(Material.GRAY_STAINED_GLASS_PANE)));
281+
```
282+
283+
### Pagination
284+
285+
Pagination simplifies the management of a large number of items in a menu. It automatically divides items into multiple pages.
286+
287+
```java
288+
MenuPagination pagination = MenuPagination.full(this);
289+
for (int i = 0; i < 100; i++) {
290+
ItemStack itemStack = new ItemStack(Material.STONE, i + 1);
291+
itemStack.setData(DataComponentTypes.MAX_STACK_SIZE, Math.min(99, i + 1));
292+
pagination.addItem(new ForbiddenSlot(itemStack));
293+
}
294+
registerEditor(pagination);
295+
```
296+
297+
### Slots Linked to Another Inventory
298+
299+
Slots can be linked to specific positions in another inventory, allowing direct interaction between multiple menus or inventories.
300+
301+
```java
302+
setSlot(4, new InventorySlot(inventory, 0));
303+
setSlot(5, new InventorySlot(inventory, 1));
304+
```
305+
306+
### Interactive Items
307+
308+
Interactive items define actions to be executed upon interaction, such as a button to close an inventory:
309+
310+
```java
311+
setSlot(9 * 4 - 1, new MenuItem(new ItemStack(Material.BARRIER)) {
312+
@Override
313+
public void click(Click click) {
314+
click.player().closeInventory();
315+
}
316+
});
317+
```

0 commit comments

Comments
 (0)