Getting Started

Warning: This page currently contains outdated information for the latest version of RestrictionHelper. This'll be updated eventually whenever I get to it.

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 start writing code.

First, you'll need to set up your build tool so that you can actually use RestrictionHelper in your project. For that, see one of these guides:

• Maven Setup
• Gradle Setup

After you've finished, continue reading below.

1. get an instance of RestrictionHelper

To get an instance of RestrictionHelper, simply instantiate a new instance and pass in your plugin's logger as the constructor's argument.

class ExamplePlugin extends JavaPlugin {

    private RestrictionHelper restrictionHelper;

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

    public RestrictionHelper getRestrictionHelper() {
        return restrictionHelper;
    }
}

2. register the appropriate restrictions

In the future, this may be done automatically for you by RestrictionHelper, but for now, your plugin must do it manually.

All you need to do is check if a specific plugin is enabled, and if so, register the appropriate restriction checker. The restriction checker has to be constructed with a DebugLogger, which RestrictionHelper generates for you.

RestrictionHelper has a ton of restrictions built-in, with more being added constantly. 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.

That's a whole lot of words for not a whole lot of code. Here's what that looks like in practice, using WorldGuard as an example:

private void setupRestrictions() {
    DebugLogger debugLogger = restrictionHelper.getDebugLogger();
    PluginManager pm = getServer().getPluginManager();

    if (pm.getPlugin("WorldGuard") != null) { 
        restrictionHelper.registerRestriction(new WorldGuardRestriction(debugLogger));
    }

    // If you'd like, you can enable the debug logger like so:
    debugLogger.setDebug(true);
}

3. check restrictions whenever you need to

Now that you've registered the restrictions you want, simply call RestrictionHelper#checkRestrictions in your code 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 you're trying to check if 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. Simply:

@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.check(event.getPlayer(), event.getClickedBlock(), ActionType.BREAK) {
        event.getClickedBlock().setType(Material.AIR); 
    }
}

Easy as that!