Skip to content

Commit ae22eec

Browse files
leolifbomleolifbom
committed
Add new code examples file
1 parent 6dfa9ff commit ae22eec

2 files changed

Lines changed: 222 additions & 0 deletions

File tree

‎examples.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Code Examples for the Mod API
2+
3+
Below are some examples of how you could hook into our mods using this API.
4+
5+
* [Waypoints](https://github.com/BadlionClient/BadlionClientModAPI/blob/master/examples.md#waypoints)
6+
* [TNT Time](https://github.com/BadlionClient/BadlionClientModAPI/blob/master/examples.md#tnt-time)
7+
* [Height Limit Overlay](https://github.com/BadlionClient/BadlionClientModAPI/blob/master/examples.md#height-limit-overlay)
8+
* [Notifications](https://github.com/BadlionClient/BadlionClientModAPI/blob/master/examples.md#notifications)
9+
* [Click Event Types](https://github.com/BadlionClient/BadlionClientModAPI/blob/master/examples.md#click-event-types)
10+
* [Levels](https://github.com/BadlionClient/BadlionClientModAPI/blob/master/examples.md#levels)
11+
12+
13+
## Waypoints
14+
15+
Using the `net.badlion.modapicommon.mods.Waypoints` class you can create waypoints remotely from your server if the
16+
user allows this on their end. Take a look at this example code below to understand how it works.
17+
18+
```java
19+
/**
20+
* You can hook into our waypoints mod as well to remotely create waypoints for players.
21+
* This example will show how you could add a waypoint for a player of their death location.
22+
*/
23+
public class PlayerDeathListener implements Listener {
24+
// A map we will use in this example for keeping track of player waypoints.
25+
private final Map<UUID, List<Waypoint>> waypoints = new HashMap<>();
26+
27+
@EventHandler
28+
public void onPlayerDeath(PlayerDeathEvent event) {
29+
final Player player = event.getEntity();
30+
final org.bukkit.Location deathLocation = player.getLocation();
31+
32+
// Here we create the location object for our waypoint,
33+
// which is going to be the location of the player when they died.
34+
final Location waypointLocation = Location.of(
35+
deathLocation.getWorld().getName(),
36+
deathLocation.getBlockX(),
37+
deathLocation.getBlockY(),
38+
deathLocation.getBlockZ());
39+
40+
// A simple boolean for whether the player is permitted to add this
41+
// waypoint into their waypoint mod, to keep it permanently.
42+
boolean allowedToAdd = true;
43+
44+
// Create a waypoint for the player who died, with the name "PlayerName's Last Death"
45+
final Waypoint waypoint = Waypoints.createWaypoint(
46+
player.getUniqueId(), // A uuid of the player this action is for
47+
waypointLocation, // The location of the waypoint
48+
player.getName() + "'s Last Death", // The name of the waypoint
49+
allowedToAdd);
50+
51+
// We can then get the list of waypoints this player has from the map we
52+
// made earlier If it does not exist, we're creating a new list value in
53+
// our map using computeIfAbsent(). And then we store the object we got from
54+
// creating the waypoint, so we can keep track of it for later use if necessary.
55+
this.waypoints.computeIfAbsent(player.getUniqueId(), key -> new ArrayList<>()).add(waypoint);
56+
}
57+
58+
// We can also delete a waypoint if we need from the player. For this, you
59+
// must have stored an instance of the created waypoint to retrieve its ID. Or just a reference to the ID
60+
public void removeDeathWaypoint(UUID uuid, Waypoint waypoint) {
61+
Waypoints.deleteWaypoint(uuid, waypoint.getId());
62+
}
63+
}
64+
```
65+
66+
67+
## TNT Time
68+
69+
Using the `net.badlion.modapicommon.mods.TNTTime` class you can change the TNT fuse time offset for players.
70+
71+
```java
72+
public class PlayerListener implements Listener {
73+
74+
@EventHandler
75+
public void onChangedWorld(PlayerChangedWorldEvent event) {
76+
boolean positiveOffset = true;
77+
78+
// Player changed to a world where the TNT fuse time is slower, let's apply that for the Badlion TNTTime mod.
79+
if ("tnt-example-world".equals(event.getPlayer().getWorld().getName())) {
80+
81+
if (positiveOffset) {
82+
// This would set the fuse offset in TNT time to be an extra 40 ticks, outover vanilla 80 ticks.
83+
TNTTime.setFuseOffset(event.getPlayer().getUniqueId(), 40);
84+
85+
} else {
86+
// You could also make the TNT time offset quicker, by instead providing a negative offset value.
87+
// The fuse time would now be 1 second (20 ticks) faster.
88+
TNTTime.setFuseOffset(event.getPlayer().getUniqueId(), -20);
89+
}
90+
91+
} else if ("world".equals(event.getPlayer().getWorld().getName())) {
92+
// When the player is back in the normal world we want to reset the fuse offset for the player, which can be easily done like below.
93+
TNTTime.resetFuseOffset(event.getPlayer().getUniqueId());
94+
}
95+
}
96+
}
97+
```
98+
99+
100+
## Height Limit Overlay
101+
102+
Using the `net.badlion.modapicommon.mods.HeightOverlay` class you can enable the height overlay mod for players on
103+
your server, and set the current map and height.
104+
105+
```java
106+
public class Game {
107+
// Find a suitable place in your code where you like to invoke the height limit mod hooks,
108+
// preferably when the game starts or players have been teleported to the right world.
109+
public void onGameStart(Collection<? extends Player> players) {
110+
final String map = "Lion Valley";
111+
final int height = 85;
112+
113+
boolean specificPlayers = true;
114+
115+
// You have two approaches here, the height overlay can either be set for the entire server; or just specific players.
116+
// Setting for specific players could be done like below
117+
118+
if (specificPlayers) {
119+
for (Player player : players) {
120+
HeightOverlay.setCurrentMap(player.getUniqueId(), map, height);
121+
}
122+
123+
} else {
124+
// Or if you would rather set the height overlay hook to apply for every player online, you would just leave out the UUID parameter.
125+
HeightOverlay.setCurrentMap(map, height);
126+
}
127+
}
128+
129+
public void onGameEnded(Collection<? extends Player> players) {
130+
// Just like with setting the current map and height, you also have an option to reset for every player or specific players.
131+
132+
boolean specificPlayers = true;
133+
134+
if (specificPlayers) {
135+
for (Player player : players) {
136+
HeightOverlay.reset(player.getUniqueId());
137+
}
138+
139+
} else {
140+
HeightOverlay.reset();
141+
}
142+
}
143+
}
144+
```
145+
146+
147+
## Notifications
148+
149+
Using the `net.badlion.modapicommon.mods.Notifications` class you can remotely send notifications to Badlion users on your server.
150+
See the `Notification#newNotification()` builder for applicable notification fields.
151+
152+
```java
153+
public class PlayerListener implements Listener {
154+
@EventHandler
155+
public void onPlayerJoin(PlayerJoinEvent event) {
156+
// A simple notification would be constructed like this, where it would show a notification
157+
// for the player for 4 seconds with the text as provided below.
158+
final Notification notification = Notification.newNotification()
159+
.setTitle("Welcome!")
160+
.setDescription("Welcome to our server, " + event.getPlayer().getName() + ".")
161+
.setDurationSeconds(4)
162+
.setLevel(Notification.Level.INFO)
163+
.build();
164+
165+
// And the notification would be sent like:
166+
Notifications.sendNotification(event.getPlayer().getUniqueId(), notification);
167+
168+
// Our notifications can also include buttons with click events, say you want
169+
// a button to bring the player to your rules page, or perform a command.
170+
Bukkit.getScheduler().runTaskLater(this.plugin, () -> {
171+
// What this code will do is create a notification where the user is presented with
172+
// two buttons, the first one will bring up a selection menu to open the URL provided,
173+
// where the second one will execute a command for the player.
174+
final Notification helpNotification = Notification.newNotification()
175+
.setTitle("Good to know")
176+
.setDescription("We remind you to check our rules, and to look for help if needed!")
177+
.setDurationSeconds(5)
178+
.setLevel(Notification.Level.INFO)
179+
.addButton(new NotificationButton("Read rules", NotificationButton.Action.OPEN_URL, "https://www.badlion.net/wiki/rules"))
180+
.addButton(new NotificationButton("Get help", NotificationButton.Action.RUN_COMMAND, "/help"))
181+
.build();
182+
183+
Notifications.sendNotification(event.getPlayer().getUniqueId(), helpNotification);
184+
}, 5 * 20); // Run this task after 5 seconds.
185+
}
186+
}
187+
```
188+
189+
### Click Event Types
190+
There are three different click event types you can use for buttons.
191+
* `OPEN_URL` opens a selection menu where the player can choose to open a url.
192+
* `SUGGEST_COMMAND` suggests the provided string in the chat field of the user.
193+
* `RUN_COMMAND` executes a command if the string starts with `/`, otherwise sends a chat message.
194+
195+
### Levels
196+
There are different notification levels to choose from.
197+
* `INFO` a simple notification with a blue info texture.
198+
* `ERROR`/`WARNING` shows that something went wrong.
199+
* `SUCCESS` shows that something went successful with a green checkmark.

‎readme.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Since update 2.0.0 this plugin now also replaces both our [CPS API](https://gith
1212

1313
With this API you can also hook into some of our mods to enhance the experience for your players even further with our client. You can read more about this and learn how to get started with our documentation on [our wiki page](https://support.badlion.net/hc/en-us/articles/4411226034066-Badlion-Client-Mod-API).
1414

15+
We've also provided some code examples on how to hook into our mods [here](https://github.com/BadlionClient/BadlionClientModAPI/blob/master/examples.md).
16+
1517
### Installation
1618

1719
How to install the Badlion Client Mod API on your server.
@@ -71,6 +73,26 @@ It will also limit the player's CPS on the right mouse button to 20, and left mo
7173
}
7274
```
7375

76+
#### Remove Hit Delay (1.8)
77+
78+
Remove Hit Delay is an option for 1.8 only where you are able to remove the hit delay, much like on 1.7.10.
79+
By default, this option is disabled and can be enabled by adding some extra data for the animations mod in the plugin config.
80+
81+
```json
82+
{
83+
"modsDisallowed": {
84+
"Animations": {
85+
"disabled": false,
86+
"extra_data": {
87+
"removeHitDelay": {
88+
"forced": true
89+
}
90+
}
91+
}
92+
}
93+
}
94+
```
95+
7496
#### Schematica printer mode
7597

7698
By default, Schematica printer cannot be enabled on servers.
@@ -131,6 +153,7 @@ Below is an example which allows the use of a few commands:
131153
+ alwaysSwing
132154
+ removeTitles
133155
+ oldEnchantGlint
156+
+ removeHitDelay
134157
+ AntiXray
135158
+ ArmorStatus
136159
+ showMaxDurability

0 commit comments

Comments
 (0)