Developer API

Accessing the API

Gradle (Kotlin DSL)

repositories {
    maven("https://repo.convallyria.com/releases")
}

dependencies {
    compileOnly("net.islandearth.rpgregions:api:1.4.5") // 1.4.5
}

Maven

<repositories>
    <repository>
        <id>convallyria-repo</id>
        <url>https://repo.convallyria.com/releases</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
           <groupId>net.islandearth.rpgregions</groupId>
           <artifactId>api</artifactId>
           <version>1.4.5</version>
           <scope>provided</scope>
    </dependency>
</dependencies>

Usage

The API is accessible through RPGRegionsAPI.getAPI(). You can then access the translator and manager instances.

StorageManager

Contains everything related to storage (i.e mysql). You can get a RPGRegionsAccount like so:

RPGRegionsAPI api = RPGRegionsAPI.getAPI();
api.getStorageManager().getAccount(...).thenAccept(account -> {
// do something with the account
});

Using removeCachedAccount will remove the account from the cache and save its data. You will generally not need to use this as it is handled by the plugin already.

IntegrationManager

Handles region protection plugin integration. Only contains methods to check if a player is in a region, and a method to handle movement of players. In the future, you will be able to create your own integration and make the plugin use it.

RPGRegionsCache

Houses all the ConfiguredRegion's. You can add, get, and remove. Example;

RPGRegionsAPI api = RPGRegionsAPI.getAPI();
ConfiguredRegion configuredRegion = api.getRegionsCache().getConfiguredRegion(...);
// do something with the configured region

RPGRegionsAccount

Contains all the discoveries a user has made in a Map<String, Discovery>, where the key is the region id. Example;

RPGRegionsAPI api = RPGRegionsAPI.getAPI();
api.getStorageManager().getAccount(...).thenAccept(account -> {
	Discovery discovery = account.getDiscoveredRegions().get(...);
  // do something with the discovery
});

You may also add discoveries using the addDiscovery(Discovery) method via the WorldDiscovery class.

Registering extensions

To register any extensions you have made, you will need to use the RPGRegionsRegistry. You should do this in your onEnable method in your plugin. Registering via the registry is easy, and a requirement example is below;

RPGRegionsAPI api = RPGRegionsAPI.getAPI();
RPGRegionsRegistry<RegionRequirement> registry = (RegionRequirementRegistry) api.getManagers().getRegistry(RegionRequirementRegistry.class);
if (registry == null) {
    getLogger().warning("Unable to register requirements");
    return;
}
registry.register(YourRequirementClass.class);

You can do the same for the other registries, which are:

• RegionRequirementRegistry
• RegionRewardRegistry
• RegionEffectRegistry

Adding in-game editing to your extensions

RPGRegions has an easy way to allow the values within your extensions to be edited. Simply add the @GuiEditable annotation to a field. The value is the name in the GUI, and you can also specify how the user edits this via the type value and setting it to one of the GuiEditableType;

CHAT,
ANVIL,
DEFAULT

Example:

@GuiEditable(value = "Locations", type = GuiEditable.GuiEditableType.CHAT)
private List<Location> locations;

You can also choose to have your class implement ICustomGuiFeedback. This will allow you to manage how the player input is managed. Example:

    @Override
    public void feedback(Player player, String input) {
        Location location = LocationUtils.getLocationFromInput(player, input);
        if (location == null) {
            player.sendMessage(ChatColor.RED + "Location could not be set: return value was null.");
            return;
        }
        // Test if it already exists
        for (Location testLocation : locations) {
            int testX = testLocation.getBlockX();
            int testY = testLocation.getBlockY();
            int testZ = testLocation.getBlockZ();
            if (location.getBlockX() == testX && location.getBlockY() == testY && location.getBlockZ() == testZ) {
                locations.remove(testLocation);
                return;
            }
        }

        addLocation(location);
        player.sendMessage(ChatColor.GREEN + "Location added.");
    }

    @Override
    public String info() {
        return "Enter 'TARGET' to set to eye location, 'SELF' for your location, or enter chat coordinates, " +
                "e.g 'x;y;z;yaw;pitch' (yaw/pitch optional). If the location already exists, it will be removed.";
    }

Adding your own rewards

Create a class that extends DiscoveryReward. This abstract class contains two methods, award(Player) and getName(). The award method will be called when the player needs to be given your reward. The name method is the name that will be displayed to users in-game. Once this class is created you can simply add it to any region you want, in code:

ConfiguredRegion configuredRegion = ...
configuredRegion.getRewards().add(...);

Example of reward class:

public class ExperienceReward extends DiscoveryReward {
	
	private final int xp;
	
	public ExperienceReward(int xp) {
		super(RPGRegionsAPI.getAPI());
		this.xp = xp;
	}
  
	public ExperienceReward(IRPGRegionsAPI api) {
		super(api);
		this.xp = 1;
	}
	
	@Override
	public void award(Player player) {
		player.giveExp(xp);
	}

	@Override
	public String getName() {
		return "Experience";
	}
}

Your reward will then be automatically saved when the server stops (or you can configure it manually then use /rpgregions reload).

Adding your own effects

Create a class that extends RegionEffect.

Example of effect class:

public class PotionRegionEffect extends RegionEffect {

	private final PotionEffect potionEffect;

	public PotionRegionEffect(PotionEffect potionEffect, boolean wearingRequired, List<ItemStack> ignoreItems) {
		super(wearingRequired, ignoreItems);
		this.potionEffect = potionEffect;
	}

	public PotionEffect getPotionEffect() {
		return potionEffect;
	}

	@Override
	public void effect(Player player) {
		player.addPotionEffect(potionEffect);
	}

	@Override
	public String getName() {
		return "PotionRegionEffect";
	}
}

Adding your own requirements

Create a class that extends RegionRequirement.

Example of requirement class:

public class LevelRequirement extends RegionRequirement {

    private final int level;

    public LevelRequirement(int level) {
        this.level = level;
    }

    @Override
    public boolean meetsRequirements(Player player) {
        return player.getLevel() >= level;
    }

    @Override
    public String getName() {
        return "Level";
    }

    @Override
    public String getText(Player player) {
        return "level " + level;
    }
}