Skip to content

Commit a92ddd8

Browse files
hudsonandreshudsonandres
authored
Adds leaderboard support to PlaceholderAPI
 - Adds placeholders to display mcMMO leaderboard information through PlaceholderAPI. - `%mcmmo_mctop_<skill>:<position>%` - `%mcmmo_mctop_overall:<position>%` - `%mcmmo_mctop_name_<skill>:<position>%` - `%mcmmo_mctop_name_overall:<position>%` - `%mcmmo_checklevel_<skill>:<level>%` - Added a new explanatory file `PLACEHOLDERS.md` detailing all the placeholders that can be used.
1 parent 3533c50 commit a92ddd8

File tree

5 files changed

+472
-1
lines changed

5 files changed

+472
-1
lines changed

‎PLACEHOLDERS.md‎

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
# mcMMO Placeholders
2+
3+
This document describes all placeholders available in mcMMO, including the new placeholders added to facilitate the creation of menus and more detailed ranking systems.
4+
5+
## Available Skills
6+
7+
All mcMMO skills can be used in the placeholders:
8+
- `acrobatics`
9+
- `alchemy`
10+
- `archery`
11+
- `axes`
12+
- `excavation`
13+
- `fishing`
14+
- `herbalism`
15+
- `mining`
16+
- `repair`
17+
- `salvage`
18+
- `smelting`
19+
- `swords`
20+
- `taming`
21+
- `unarmed`
22+
- `woodcutting`
23+
- `crossbows`
24+
- `tridents`
25+
- `maces`
26+
27+
---
28+
29+
## Skill Placeholders (Per Skill)
30+
31+
The following placeholders are available for **all skills** listed above:
32+
33+
### Skill Level
34+
**Syntax:** `%mcmmo_level_<skill>%`
35+
36+
Returns the player's current level in the specified skill.
37+
38+
**Examples:**
39+
- `%mcmmo_level_mining%` - Returns Mining level (e.g., "75")
40+
- `%mcmmo_level_combat%` - Returns Combat level
41+
- `%mcmmo_level_woodcutting%` - Returns Woodcutting level
42+
43+
### Current Skill XP
44+
**Syntax:** `%mcmmo_xp_<skill>%`
45+
46+
Returns the current amount of XP the player has in the skill.
47+
48+
**Examples:**
49+
- `%mcmmo_xp_mining%` - Returns current Mining XP (e.g., "1245")
50+
- `%mcmmo_xp_fishing%` - Returns current Fishing XP
51+
52+
### XP Needed for Next Level
53+
**Syntax:** `%mcmmo_xp_needed_<skill>%`
54+
55+
Returns the total amount of XP needed to reach the next level.
56+
57+
**Examples:**
58+
- `%mcmmo_xp_needed_mining%` - Returns XP needed (e.g., "2000")
59+
- `%mcmmo_xp_needed_combat%` - Returns XP needed for next level
60+
61+
### XP Remaining for Next Level
62+
**Syntax:** `%mcmmo_xp_remaining_<skill>%`
63+
64+
Returns how much XP is still needed to level up.
65+
66+
**Examples:**
67+
- `%mcmmo_xp_remaining_mining%` - Returns remaining XP (e.g., "755")
68+
- `%mcmmo_xp_remaining_fishing%` - XP needed for the next level
69+
70+
### Skill Rank Position
71+
**Syntax:** `%mcmmo_rank_<skill>%`
72+
73+
Returns the player's position in the leaderboard for that skill.
74+
75+
**Examples:**
76+
- `%mcmmo_rank_mining%` - Returns "12" if the player is in 12th place
77+
- `%mcmmo_rank_combat%` - Position in Combat ranking
78+
79+
### Skill XP Rate
80+
**Syntax:** `%mcmmo_xprate_<skill>%`
81+
82+
Returns the XP multiplier the player has for that skill (based on permissions).
83+
84+
**Examples:**
85+
- `%mcmmo_xprate_mining%` - Returns "2.0" if they have double XP
86+
- `%mcmmo_xprate_fishing%` - Returns "1.5" if they have 1.5x XP
87+
88+
---
89+
90+
## Power Level Placeholders (General)
91+
92+
### Total Power Level
93+
**Syntax:** `%mcmmo_power_level%`
94+
95+
Returns the player's total power level (sum of all skill levels).
96+
97+
**Example:**
98+
- `%mcmmo_power_level%` - Returns "850"
99+
100+
### Power Level Cap
101+
**Syntax:** `%mcmmo_power_level_cap%`
102+
103+
Returns the maximum power level cap configured on the server.
104+
105+
**Example:**
106+
- `%mcmmo_power_level_cap%` - Returns "2000"
107+
108+
### Global XP Rate
109+
**Syntax:** `%mcmmo_xprate%`
110+
111+
Returns the global XP multiplier configured on the server.
112+
113+
**Example:**
114+
- `%mcmmo_xprate%` - Returns "1.5"
115+
116+
### XP Event Active
117+
**Syntax:** `%mcmmo_is_xp_event_active%`
118+
119+
Returns whether an XP event is active on the server.
120+
121+
**Return:**
122+
- `true` - If there is an active XP event
123+
- `false` - If there is no event
124+
125+
---
126+
127+
## Party Placeholders
128+
129+
### Is in Party
130+
**Syntax:** `%mcmmo_in_party%`
131+
132+
Checks if the player is in a party.
133+
134+
**Return:**
135+
- `true` - If in a party
136+
- `false` - If not in a party
137+
138+
### Party Name
139+
**Syntax:** `%mcmmo_party_name%`
140+
141+
Returns the player's party name (empty if not in any).
142+
143+
**Example:**
144+
- `%mcmmo_party_name%` - Returns "Adventurers"
145+
146+
### Is Party Leader
147+
**Syntax:** `%mcmmo_is_party_leader%`
148+
149+
Checks if the player is the party leader.
150+
151+
**Return:**
152+
- `true` - If they are the leader
153+
- `false` - If they are not the leader or not in a party
154+
155+
### Party Leader Name
156+
**Syntax:** `%mcmmo_party_leader%`
157+
158+
Returns the name of the party leader.
159+
160+
**Example:**
161+
- `%mcmmo_party_leader%` - Returns "Steve"
162+
163+
### Party Size
164+
**Syntax:** `%mcmmo_party_size%`
165+
166+
Returns the number of members in the party.
167+
168+
**Example:**
169+
- `%mcmmo_party_size%` - Returns "5"
170+
171+
---
172+
173+
## Leaderboard/McTop Placeholders
174+
175+
### Get Value/Level at Position X (✨ NEW)
176+
177+
Returns the value (level or power level) of the player at position X in the ranking.
178+
179+
**Syntax:**
180+
- `%mcmmo_mctop_<skill>:<position>%` - For a specific skill
181+
- `%mcmmo_mctop_overall:<position>%` - For overall ranking (power level)
182+
183+
**Examples:**
184+
- `%mcmmo_mctop_mining:1%` - Returns the Mining level of the 1st place player
185+
- `%mcmmo_mctop_combat:5%` - Returns the Combat level of the 5th place player
186+
- `%mcmmo_mctop_overall:1%` - Returns the power level of the 1st place player
187+
188+
### Get Player Name at Position X (✨ NEW)
189+
190+
Returns the player's name at position X in the ranking.
191+
192+
**Syntax:**
193+
- `%mcmmo_mctop_name_<skill>:<position>%` - For a specific skill
194+
- `%mcmmo_mctop_name_overall:<position>%` - For overall ranking
195+
196+
**Examples:**
197+
- `%mcmmo_mctop_name_mining:1%` - Returns the name of the 1st place player in Mining
198+
- `%mcmmo_mctop_name_combat:10%` - Returns the name of the 10th place player in Combat
199+
- `%mcmmo_mctop_name_overall:1%` - Returns the name of the 1st place player in overall ranking
200+
201+
### Get Your Overall Rank Position (✨ NEW)
202+
203+
Returns the player's position in the overall ranking (power level).
204+
205+
**Syntax:**
206+
- `%mcmmo_rank_overall%`
207+
208+
**Example:**
209+
- `%mcmmo_rank_overall%` - Returns "15" if the player is in 15th place
210+
211+
---
212+
213+
## Level Check Placeholder (✨ NEW)
214+
215+
Checks if the player has reached the required level in a specific skill.
216+
217+
**Syntax:**
218+
- `%mcmmo_checklevel_<skill>:<level>%`
219+
220+
**Return:**
221+
- `✔` - If the player has the required level or higher
222+
- `✘` - If the player does NOT have the required level
223+
224+
**Examples:**
225+
- `%mcmmo_checklevel_mining:50%` - Returns ✔ if player has Mining level 50+, otherwise ✘
226+
- `%mcmmo_checklevel_combat:100%` - Returns ✔ if player has Combat level 100+, otherwise ✘
227+
- `%mcmmo_checklevel_woodcutting:25%` - Returns ✔ if player has Woodcutting level 25+, otherwise ✘
228+
229+
---
230+
231+
## Available Skills Reference
232+
233+
All mcMMO skills that can be used in the placeholders above:
234+
- `acrobatics` - Acrobatics
235+
- `alchemy` - Alchemy
236+
- `archery` - Archery
237+
- `axes` - Axes
238+
- `excavation` - Excavation
239+
- `fishing` - Fishing
240+
- `herbalism` - Herbalism
241+
- `mining` - Mining
242+
- `repair` - Repair
243+
- `salvage` - Salvage
244+
- `smelting` - Smelting
245+
- `swords` - Swords
246+
- `taming` - Taming
247+
- `unarmed` - Unarmed
248+
- `woodcutting` - Woodcutting
249+
- `crossbows` - Crossbows
250+
- `tridents` - Tridents
251+
- `maces` - Maces
252+
253+
---
254+
255+
## Menu Usage Examples
256+
257+
### Top 10 Mining Menu
258+
```yaml
259+
display:
260+
name: "&6Top 10 - Mining"
261+
lore:
262+
- "&71st - %mcmmo_mctop_name_mining:1% &f- &e%mcmmo_mctop_mining:1%"
263+
- "&72nd - %mcmmo_mctop_name_mining:2% &f- &e%mcmmo_mctop_mining:2%"
264+
- "&73rd - %mcmmo_mctop_name_mining:3% &f- &e%mcmmo_mctop_mining:3%"
265+
- "&74th - %mcmmo_mctop_name_mining:4% &f- &e%mcmmo_mctop_mining:4%"
266+
- "&75th - %mcmmo_mctop_name_mining:5% &f- &e%mcmmo_mctop_mining:5%"
267+
```
268+
269+
### Overall Ranking Menu
270+
```yaml
271+
display:
272+
name: "&6Overall Ranking - Power Level"
273+
lore:
274+
- "&7Your position: &e#%mcmmo_rank_overall%"
275+
- ""
276+
- "&6Top 3:"
277+
- "&e1st - %mcmmo_mctop_name_overall:1% &f- &6%mcmmo_mctop_overall:1%"
278+
- "&e2nd - %mcmmo_mctop_name_overall:2% &f- &6%mcmmo_mctop_overall:2%"
279+
- "&e3rd - %mcmmo_mctop_name_overall:3% &f- &6%mcmmo_mctop_overall:3%"
280+
```
281+
282+
### Requirement Check Menu
283+
```yaml
284+
display:
285+
name: "&6Unlock Special Ability"
286+
lore:
287+
- "&7Requirements:"
288+
- "&7Mining Level 50: %mcmmo_checklevel_mining:50%"
289+
- "&7Combat Level 75: %mcmmo_checklevel_combat:75%"
290+
- "&7Woodcutting Level 30: %mcmmo_checklevel_woodcutting:30%"
291+
```
292+
293+
## Technical Notes
294+
295+
- Placeholders work with PlaceholderAPI
296+
- Data is obtained directly from the mcMMO database
297+
- PlaceholderAPI cache is used to optimize queries
298+
- Invalid positions (less than 1 or greater than total players) return empty string
299+
- Invalid levels or non-existent skills return ✘ for checklevel

‎src/main/java/com/gmail/nossr50/placeholders/CheckLevelPlaceholder.java‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
package com.gmail.nossr50.placeholders;
2+
3+
import com.gmail.nossr50.datatypes.skills.PrimarySkillType;
4+
import org.bukkit.entity.Player;
5+
6+
/**
7+
* Placeholder for checking if a player has reached a specific level in a skill
8+
* Usage: %mcmmo_checklevel_<skill>:<level>%
9+
* Returns: ✔ if player has the level, ✘ if not
10+
*/
11+
public class CheckLevelPlaceholder implements Placeholder {
12+
private final PapiExpansion papiExpansion;
13+
private final PrimarySkillType skill;
14+
15+
public CheckLevelPlaceholder(PapiExpansion papiExpansion, PrimarySkillType skill) {
16+
this.papiExpansion = papiExpansion;
17+
this.skill = skill;
18+
}
19+
20+
@Override
21+
public String process(Player player, String params) {
22+
if (params == null || params.isEmpty()) {
23+
return "§c✘";
24+
}
25+
26+
int requiredLevel;
27+
try {
28+
requiredLevel = Integer.parseInt(params);
29+
} catch (NumberFormatException e) {
30+
return "§c✘";
31+
}
32+
33+
Integer currentLevel = papiExpansion.getSkillLevel(skill, player);
34+
if (currentLevel == null) {
35+
return "§c✘";
36+
}
37+
38+
return currentLevel >= requiredLevel ? "§a✔" : "§c✘";
39+
}
40+
41+
@Override
42+
public String getName() {
43+
return "checklevel_" + skill.toString().toLowerCase();
44+
}
45+
}

0 commit comments

Comments
 (0)