Getting Started - TehBrian/RestrictionHelper GitHub Wiki

Welcome to the Getting Started guide! The goal of this little document is to help you learn how to use RestrictionHelper as fast as possible so that you can stop worrying about restrictions and instead start writing the fun parts of your plugin.

1. add the RestrictionHelper library to your project

First, you'll need to set up your build tool to import RestrictionHelper into your project. For that, see one of these guides:

• Maven Setup
• Gradle Setup

2. create an instance of RestrictionHelper

To get an instance of RestrictionHelper, simply instantiate the implementation specific to your platform. If you're using Spigot or one of its forks, such as Paper, use SpigotRestrictionHelper.

class ExamplePlugin extends JavaPlugin {
  private RestrictionHelper restrictionHelper;

  public void onEnable() {
    this.restrictionHelper = new SpigotRestrictionHelper();
  }

  public RestrictionHelper getRestrictionHelper() {
    return this.restrictionHelper;
  }
}

3. register the appropriate restrictions

Once you have an instance of RestrictionHelper, you must register the restrictions for the plugins that you would like to check against.

A restriction is what actually integrates with a plugin to check whether a player has permission to build in a certain area.

RestrictionHelper currently has restrictions for PlotSquared and WorldGuard built-in, with more on the way. The hope is that you won't have to write a restriction checker yourself. For a list of built-in restrictions, look at the restrictions package in RestrictionHelper's source.

You can either register restrictions with RestrictionLoader or by checking for plugins manually.

register restrictions with RestrictionLoader (recommended)

To register restrictions with RestrictionLoader, instantiate the implementation specific to your platform. (So, if you're using Spigot or one of its forks, such as Paper, use SpigotRestrictionLoader.)

Pass to the constructor: your plugin's logger, the list of plugins to check against, and the restrictions that should be registered if a relevant plugin is detected.

The RestrictionLoader will then check each plugin on the server. If it detects a plugin with a name, version, and main class that corresponds to one of the restrictions, it will register the corresponding restriction.

public void onEnable() {
  final RestrictionLoader loader = new SpigotRestrictionLoader(
      this.getSLF4JLogger(),
      Arrays.asList(this.getServer().getPluginManager().getPlugins()),
      List.of(R_PlotSquared_6.class, R_WorldGuard_7.class)
  );

  loader.load(this.restrictionHelper);
}

register restrictions manually

You can also register restrictions manually. To do so, check whether a specific plugin is enabled, and if so, register the corresponding restriction checker.

public void onEnable() {
  final PluginManager pm = this.getServer().getPluginManager();
  final Logger logger = this.getSLF4JLogger();
  if (pm.getPlugin("WorldGuard") != null) { 
    this.restrictionHelper.registerRestriction(new R_WorldGuard_7(logger));
  }
  if (pm.getPlugin("PlotSquared") != null) { 
    this.restrictionHelper.registerRestriction(new R_PlotSquared_6(logger));
  }
  // And so on for every other plugin.
}

4. check RestrictionHelper as needed

Now that you've registered the restrictions, simply call RestrictionHelper#checkRestrictions wherever you'd like.

The three arguments that you must pass are the player, the location you'd like to check, and the type of action that you're trying to check whether the player has access to perform.

As an example, let's say we'd like to make the player destroy any block they click on, but we want to make sure the player has access to do that.

@EventHandler
public void onInteract(PlayerInteractEvent event) {
  // Notice we pass the BREAK ActionType rather than INTERACT, because we're checking
  // whether the player has permission to break that block. It doesn't matter what
  // the root cause of the action is.
  if (restrictionHelper.checkRestrictions(event.getPlayer(), event.getClickedBlock(), ActionType.BREAK) {
    event.getClickedBlock().setType(Material.AIR); 
  }
}

Easy as that!