What is the Badlion Mod API?

The Badlion Mod API is a public plugin to give servers the ability to deactivate certain mods or features of mods while they are playing on the server. Since the version 2.0 of our mod API plugins, it is now also possible to limit CPS and use our Timer API directly in this plugin, where previously these were located in different repositories.

You can read more about the Badlion Mod API and the installation process on our GitHub repository page.

Hooking into Badlion mods with the API

Since version 2.0 of our mod API, it is now possible to directly hook into a few of our mods. Currently, we support this for Waypoints, TNT Time, and Height Limit Overlay.

This article will go through how to set up an example plugin, and how to hook into our mods using our API.

Getting started

Before getting started, you need to make sure to have done the following:

1. Clone our Mod API repository from GitHub, and build it once for the dependencies to load.
   
   
2. Create a maven project for your plugin, with the following pom file contents
   
   If you are building a Bukkit plugin, the artifactId should be blcmodapibukkit for below 1.17, or blcmodapibukkit-1.17 for 1.17.
   If you are building a Bungee plugin, the artifactId should be blcmodapibungee.
   

   <dependencies>
      <dependency>
          <groupId>net.badlion</groupId>
          <artifactId>ARTIFACT-ID-HERE</artifactId>
          <version>2.0.0</version>
          <scope>provided</scope>
      </dependency>
   </dependencies>

   For the dependency to resolve correctly, you might need to build the cloned mod API project once, simply by executing mvn clean install in the directory you cloned it in.
   
   
3. In your plugin.yml, you should add the following to make sure your plugin loads after the Badlion Mod API:
   

   depend:
     - BadlionClientModAPI

4. Make sure to place the BLC plugin jar file inside of the server plugin folder, along with your own plugin.

Using the Badlion Mod API

As previously mentioned, we currently only support a few mods for our API, and you can access these by importing the class matching the name of the mod.

Let’s go over the different mods we are currently supporting, and how to perform actions with them. In these examples, we will be working with a Bukkit plugin.

Waypoints

Accessing the net.badlion.modapicommon.mods.Waypoints class you can create waypoints remotely from your server if the user allows this on their end. An example of what this could look like:

/**
* You can hook into our waypoints mod as well to remotely create waypoints for players.
* This example will show how you could add a waypoint for a player when they perform a command.
*/
public static class HomeCommand implements CommandExecutor {
  // A map we will use in this example for keeping track of player waypoints.
  private final Map<UUID, List<Waypoint>> playerWaypoints = new HashMap<>();

  @Override
  public boolean onCommand(CommandSender sender, Command command, String s, String[] args) {
     if (!(sender instanceof Player)) {
        return false;
     }

     final Player player = (Player) sender;

     if (args.length == 0) {
        return false;
     }

     // This would listen for when a player executes /<command-name> sethome
     if ("sethome".equalsIgnoreCase(args[0])) {
        // The location of the player executing the command
        final org.bukkit.Location location = player.getLocation();
        if (location.getWorld() == null) {
           return false;
        }

        // Here we create the location object for our waypoint, which is going to be where the player is located at.
        final Location waypointLocation = Location.of(location.getWorld().getName(), location.getBlockX(), location.getBlockY(), location.getBlockZ());

        // A simple boolean for whether or not the player is permitted to add this waypoint into their waypoint mod, to keep it permanently.
        boolean allowedToAdd = true;

        Waypoint waypoint = Waypoints.createWaypoint(player.getUniqueId(), waypointLocation, ChatColor.GREEN + player.getName() + "'s Home", allowedToAdd);

        // Here we're getting the list of waypoints this player has from the map we made, or creating a new list if none is present.
        final List<Waypoint> waypoints = this.playerWaypoints.computeIfAbsent(player.getUniqueId(), k -> new ArrayList<>());
        // And add the waypoint object we got from creating the waypoint, so that we can keep track of it for later use if necessary.
        waypoints.add(waypoint);

     } else if ("remove".equalsIgnoreCase(args[0])) {
        Iterator<Waypoint> waypointIterator = this.playerWaypoints.computeIfAbsent(player.getUniqueId(), k -> new ArrayList<>()).stream()
           .filter(waypoint -> waypoint.getName().contains(player.getName()))
           .iterator();

        while (waypointIterator.hasNext()) {
           final Waypoint waypoint = waypointIterator.next();

           waypointIterator.remove();

        // Here we can simply delete the waypoint from a player by knowing the ID of the waypoint.
        Waypoints.deleteWaypoint(player.getUniqueId(), waypoint.getId());
        }
     }

     return false;
  }
}

TNT Time

Accessing the net.badlion.modapicommon.mods.TNTTime class you can change the TNT fuse time offset for players.

@EventHandler
public void onChangedWorld(PlayerChangedWorldEvent event) {
  boolean positiveOffset = true;

  // Player changed to a world where the TNT fuse time is slower, let's apply that for the Badlion TNTTime mod.
  if ("tnt-example-world".equals(event.getPlayer().getWorld().getName())) {

     if (positiveOffset) {
        // This would set the fuse offset in TNT time to be an extra 40 ticks, outover vanilla 80 ticks.
        TNTTime.setFuseOffset(event.getPlayer().getUniqueId(), 40);

     } else {
        // You could also make the TNT time offset quicker, by instead providing a negative offset value.
        // The fuse time would now be 1 second (20 ticks) faster.
        TNTTime.setFuseOffset(event.getPlayer().getUniqueId(), -20);
     }

  } else if ("world".equals(event.getPlayer().getWorld().getName())) {
     // 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.
     TNTTime.resetFuseOffset(event.getPlayer().getUniqueId());
  }
}

Height Limit Overlay

Accessing the net.badlion.modapicommon.mods.HeightOverlay class you can enable the height overlay mod for players on your server, and set the current map and height.

// Find a suitable place in your code where you like to invoke the height limit mod hooks,
// preferably when the game starts or players have been teleported to the right world.
public void onGameStart(Collection<? extends Player> players) {
  final String map = "Lion Valley";
  final int height = 85;

  boolean specificPlayers = true;

  // You have two approaches here, the height overlay can either be set for the entire server; or just specific players.
  // Setting for specific players could be done like below

  if (specificPlayers) {
     for (Player player : players) {
        HeightOverlay.setCurrentMap(player.getUniqueId(), map, height);
     }

  } else {
     // Or if you would rather set the height overlay hook to apply for every player online, you would just leave out the UUID parameter.
     HeightOverlay.setCurrentMap(map, height);
  }
}

public void onGameEnded(Collection<? extends Player> players) {
  // Just like with setting the current map and height, you also have an option to reset for every player or specific players.

  boolean specificPlayers = true;

  if (specificPlayers) {
     for (Player player : players) {
        HeightOverlay.reset(player.getUniqueId());
     }

  } else {
     HeightOverlay.reset();
  }
}

The waypoints.json configuration

When you use the Bukkit version of our Mod API a file named waypoints.json will be created. When players join your server, these waypoints will automatically be added to them when they join the server. By default, this file contains an example of what a waypoint would look like, and from there you can create further waypoints.

In the configuration, you will be presented with a json tree of waypoints. allowedToAdd specifies whether or not the client should be able to permanently save this waypoint to their waypoint mod. Color codes are supported in the name field of waypoints.

Two waypoints could for example look like this:

[
  {
    "location": {
      "world": "world",
      "x": 100,
      "y": 20,
      "z": 100
    },
    "name": "World Waypoint",
    "allowToAdd": false
  },
  {
    "location": {
      "world": "world_nether",
      "x": 0,
      "y": 50,
      "z": 0
    },
    "name": "Center of Nether",
    "allowToAdd": true
  }
]

For changes to apply in this configuration you must reboot the server.