-
Notifications
You must be signed in to change notification settings - Fork 35
Quests API
Source - http://web.archive.org/web/20140908183254/http://blackvein.net/api.html
The API for Quests is shrouded in mystery. Developed by Blackvein somewhere between dinosaur times and the Stone Age, there were originally several parts to it. Each part was a different jar library which could be used to create unique, custom modules. These modules would then be placed in the Quests/modules folder.
Those aforementioned libraries have been lost to the Interwebs. Ahead lies the documentation, preserved for posterity.
Building a Quest Requirement is very simple. To get started, create a Java class that extends the CustomRequirement class found in the Custom Requirement library. After that, check out this example of a Custom Requirement where the player must have a particular name in order to take the Quest:
package me.blackvein;
import java.util.Map;
import me.blackvein.quests.CustomRequirement;
import org.bukkit.entity.Player;
public class NameRequirement extends CustomRequirement {
public NameRequirement() {
this.setName("Name Requirement");
this.setAuthor("Blackvein");
this.addData("Name");
this.addData("Case-Sensitive");
this.addDescription("Name", "The player's name must contain this value in order to take the Quest.");
this.addDescription("Case-Sensitive", "Should the name check be case-sensitive or not? (Enter \'true\' or \'false\'");
}
@Override
public boolean testRequirement(Player player, Map<String, Object> data) {
String caseSensitive = (String) data.get("Case-Sensitive");
if(caseSensitive.equalsIgnoreCase("true"))
return player.getName().contains((String)data.get("Name"));
else
return player.getName().toLowerCase().contains(((String)data.get("Name")).toLowerCase());
}
}
In the constructor of your class, you may use any of the following methods:
- setName() - Sets the name of the Custom Requirement
- setAuthor() - Sets the author of the Custom Requirement
- addData() - Add a piece of data that the user must give input for when they add the Custom Requirement to their Quest.
- addDescription() - Add a description for a piece of data. Note: The first argument must match a valid data name that has been added. Inside testRequirement() is where you perform your logic to determine whether the player passes the requirement, returning true if they do, and false if they do not.
The data Map contains the data that the person who created the Quest gave to it. In this example, the data Map contains the two values for 'Name' and 'Case-Sensitive'.
Note: Although the data Map values are Objects, they are in effect Strings and cannot be cast to anything else. You must perform manual type-conversion if you want to obtain integers, booleans and whatnot.
###Custom Rewards
Building a Quest Reward is very simple. To get started, create a Java class that extends the CustomReward class found in the Custom Reward library. After that, check out this example of a Custom Reward where a player gets a GUI Inventory that pops up containing iron, gold and diamonds:
package me.blackvein;
import java.util.Map;
import me.blackvein.quests.CustomReward;
import org.bukkit.Bukkit;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import org.bukkit.inventory.Inventory;
import org.bukkit.inventory.ItemStack;
public class LootReward extends CustomReward {
public LootReward() {
this.setName("Loot Reward");
this.setAuthor("Blackvein");
this.setRewardName("Loot Chest");
this.addData("Title");
this.addData("Iron");
this.addData("Gold");
this.addData("Diamonds");
this.addDescription("Title", "Title of the loot inventory interface.");
this.addDescription("Iron", "Enter the number of iron ingots to give to the player in the loot chest.");
this.addDescription("Gold", "Enter the number of gold ingots to give to the player in the loot chest.");
this.addDescription("Diamonds", "Enter the number of diamonds to give to the player in the loot chest.");
}
@Override
public void giveReward(Player player, Map<String, Object> data) {
String title = (String) data.get("Title");
String iron = (String) data.get("Iron");
String gold = (String) data.get("Gold");
String diamonds = (String) data.get("Diamonds");
int numIron = 0;
int numGold = 0;
int numDiamonds = 0;
try{
numIron = Integer.parseInt(iron);
}catch(NumberFormatException nfe){
//Do nothing, invalid data = 0 amount
}
try{
numGold = Integer.parseInt(gold);
}catch(NumberFormatException nfe){
//Do nothing, invalid data = 0 amount
}
try{
numDiamonds = Integer.parseInt(diamonds);
}catch(NumberFormatException nfe){
//Do nothing, invalid data = 0 amount
}
Inventory inv = Bukkit.getServer().createInventory(player, 3, title);
int index = 0;
if(numIron > 0){
inv.setItem(index, new ItemStack(Material.IRON_INGOT, numIron > 64 ? 64 : numIron));
index++;
}
if(numGold > 0){
inv.setItem(index, new ItemStack(Material.GOLD_INGOT, numGold > 64 ? 64 : numGold));
index++;
}
if(numDiamonds > 0){
inv.setItem(index, new ItemStack(Material.DIAMOND, numDiamonds > 64 ? 64 : numDiamonds));
}
player.openInventory(inv);
}
}
In the constructor of your class, you may use any of the following methods:
- setName() - Sets the name of the Custom Reward
- setAuthor() - Sets the author of the Custom Reward
- setRewardName() - Sets the reward name (text that will appear when the player completes the Quest) of the Custom Reward.
- addData() - Add a piece of data that the user must give input for when they add the Custom Reward to their Quest.
- addDescription() - Add a description for a piece of data. Note: The first argument must match a valid data name that has been added.
Inside giveReward() is where you perform your logic to give the player whatever it is your Custom Reward gives. The data Map contains the data that the person who created the Quest gave to it. In this example, the data Map contains four values: One for the title of the GUI, and three for the amount of iron/gold/diamonds.
Note: Although the data Map values are Objects, they are in effect Strings and cannot be cast to anything else. You must perform manual type-conversion if you want to obtain integers, booleans and whatnot.
###Custom Objectives
Building a Quest Objective is a bit more complicated than Requirements/Rewards. To get started, create a Java class that extends the CustomObjective class found in the Custom Objective library. It must also implement the Bukkit Listener class. After that, check out this example of a Custom Objective where a player must gain a certain amount of experience to advance:
package me.blackvein;
import me.blackvein.quests.CustomObjective;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerExpChangeEvent;
public class ExperienceObjective extends CustomObjective {
public ExperienceObjective() {
this.setName("Experience Objective");
this.setAuthor("Blackvein");
this.setEnableCount(true);
this.setShowCount(true);
this.setCountPrompt("Enter the experience points that the player must acquire:");
this.setDisplay("Acquire experience points: %count%");
}
@EventHandler
public void onPlayerExpChange(PlayerExpChangeEvent evt){
if(evt.getAmount() > 0){
incrementObjective(evt.getPlayer(), this, evt.getAmount());
}
}
}
In the constructor of your class, you may use any of the following methods:
- setName() - Sets the name of the Custom Objective
- setAuthor() - Sets the author of the Custom Objective
- setEnableCount() - Sets whether the Custom Objective 'counts' (the player needs to repeat a task multiple times)
- setShowCount() - Sets whether the player is shown their progress in achieving the Custom Objective (set this to false if you disable the count)
- setCountPrompt() - Sets the prompt for the user when they set the count for the objective. It should be something that tells the user what the count is. In the case above, it explains that the count is the number of experience that the player must acquire.
- setDisplay() - Sets the display for the objective (The text that is shown to the player in their objectives list). Note: Place %count% where you want the objective count to appear. You may also put %data%, where data is the name of a piece of data you have added. It will replace that with the value entered by the user.
- addData() - Add a piece of data that the user must give input for when they add the Custom Objective to their Quest.
- addDescription() - Add a description for a piece of data. Note: The first argument must match a valid data name that has been added. Your class must implement Listener. Create EventHandlers for the events related to your objective. Quests will automatically register the class as a listener. Inside your EventHandlers, determine whether the player has completed part or all of the objective, and then use incrementObjective() to advance the player. The first and the second argument of incrementObjective() should always be the player and 'this' respectively. The third argument is how much to increment the objective by. Note: If your objective does not have a count, still use the incrementObjective() method but just increment it by 1 to signal that the objective has been completed.
Here is another example of a Custom Objective using data. This objective requires the player to drop a certain number of a certain type of item:
package me.blackvein;
import java.util.Map;
import me.blackvein.quests.CustomObjective;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerDropItemEvent;
import org.bukkit.inventory.ItemStack;
public class DropItemObjective extends CustomObjective {
public DropItemObjective() {
this.setName("Drop Item Objective");
this.setAuthor("Blackvein");
this.setEnableCount(true);
this.setShowCount(true);
this.setCountPrompt("Enter the amount that the player must drop:");
this.addData("Item ID");
this.addData("Item Name");
this.addDescription("Item ID", "Enter the ID of the item that the player must drop");
this.addDescription("Item Name", "Enter the name of the item that the player must drop");
this.setDisplay("Drop %Item Name%: %count%");
}
@EventHandler
public void onPlayerDropItem(PlayerDropItemEvent evt){
Map<String, Object> map = getDatamap(evt.getPlayer(), this);
ItemStack stack = evt.getItemDrop().getItemStack();
int id = Integer.parseInt((String) map.get("Item ID"));
if(stack.getTypeId() == id)
incrementObjective(evt.getPlayer(), this, stack.getAmount());
}
}
''''
The data Map contains the data that the person who created the Quest gave to it. In this example, the data Map contains two values: One for the ID of the item that the player needs to drop, and one for the name.
Note: Although the data Map values are Objects, they are in effect Strings and cannot be cast to anything else. You must perform manual type-conversion if you want to obtain integers, booleans and whatnot.