HOW TO CONFIGURE - THE BASICS
There are four important terms that will be used within this tutorial, so please read over what they mean first. Note that this tutorial is fairly lengthy as it covers explanations, answering the "why" behind the configuration's format. If you cannot be bothered by explanations, there will be a simpler tutorial in the future, but it is recommended, for the sake of understanding, that you understand the "why" behind things, not just the "what" and "how".
These terms are (explained in this order):
What exactly does this plugin do?
While the plugin is called "OtherDrops", originally designed for making drops more dynamic, it can do much more. In short, it can make the Minecraft experience much more dynamic, all at the server administrator's discretion. On top of that, it is fairly intuitive to configure, requires no knowledge of code, and has immense potential.
- The plugin, in a nutshell, allows you to take any block/entity you want, have it act in some new way in response to any trigger you desire.
What is an "Object"?
For this plugin, an "object" is the thing you want to modify in some way. For example, if you want to make a dirt block react to something, or do something differently (in other words, modify), then the dirt block will be your object.
What is a "Condition"?
The "condition" is/are the event(s) required for some kind of action to happen. For example, if you want a creeper to drop an item when you right click it, but only when it's raining, you could say that raining weather AND right-clicking are the conditions required for the action to occur. Note that they must both happen - in a way, they combine to form a "singular" requirement, or "trigger".
- A "trigger" just means all the "conditions" required for the action to occur.
What is an "Action"?
It is the "effect" that occurs after a set of "conditions" are met. Using the same creeper example from before, the effect of fulfilling the conditions is that an item gets dropped. The item-dropping is the "action" that the plugin is being told to undertake (AKA the "effect" of the "trigger"). You can think of an action as an event that happens.
- In essence, it can help to think of these three terms as the cycle of Cause & Effect with an Agent in between. The object is the agent, the cause is the trigger, and the effect is the action.
What is an "Entry"?
In real life, with every cause, there are one or more effects. In this plugin, with every set of conditions, there are one or more actions that occur as a result of those conditions being met. An entry modifies the object by giving it a "trigger", with one or more "actions" in response to that trigger. Basically, it adds a single "cause-and-effect" to the object. The creeper example is one "entry", as it consists of two conditions, along with its effect.
An Example: Step-by-Step
Here is an example of an object and two entries modifying that object.
- (Remember to space properly for YAML! Pay attention to the spacing used here.)
DIRT: # That's your object - tool: IRON_SWORD # The dash, "-", denotes a new entry trigger: LEFT_CLICK # "tool" is one condition, and "trigger" is another condition drop: STICK # "chance" and "drop" are the "actions" to be undertaken within this entry chance: 1% # This means that an entry's actions can only happen under that same entry's conditions - tool: STONE_SWORD # There is another dash, denoting that this is an entirely separate entry for the same object damageattacker: 2 # This is another type of action; note that specifying no condition means the plugin defaults to using "breaking-block" or "killing-entity" as the condition
Here, we have two entries. They both apply to "DIRT", so we can expect that "DIRT" is being modified. The first entry denotes that you have a "trigger": left-clicking the object, "DIRT", with an "IRON_SWORD". Only that combination will do - left-clicking without an iron sword, or right-clicking with an iron sword will not do anything (because we did not tell the plugin to do anything for those triggers). We next know that this "trigger" results in two actions: a 1% chance for the effect (all actions within this entry) to even happen at all, and for a "STICK" to drop should the effect occur successfully.
The next dash denotes an entirely separate entry, which means we can expect another trigger, followed by an action. Here, it tells us that if we break a dirt block WITH, and ONLY WITH a "STONE_SWORD", the attacker (person who broke the block) will be damaged two points.
What was the point of all that explanation?
Think about what we have just achieved. In that example, we were able to add new triggers and events (in response to those triggers), all for a dirt block. Given the amount of objects vanilla Minecraft can offer, combined with the parameters that this plugin provides, the possibilities are endless, capped only by your imagination and the technical limitations of Bukkit. In short (and within certain bounds), you can...
Quote from OtherDrops:
Make anything do anything, anyhow!
- (Okay, okay, I realise that isn't a 100% accurate quote, but the meaning is clearer here as I'm using "do" instead of "drop".)
You've been using the term "parameter", but you haven't elaborated on it!
The entire above portion is to get you used to the "format" of this plugin - in essence, to get you to see how it works and thinks. Now to explain some of the actual stuff.
A parameter is a variable that tells the plugin to "listen" for something, or to "take action" after having heard something specific. Using the terms above, a parameter is either a variable-condition, or a variable-action: thus it comes in two types (which should be fairly obvious by now). These parameters basically tell the plugin what to do and when (after you've specified an object, of course).
It should be fairly intuitive to tell which parameter falls under which of the two categories. Parameters like "tool" are conditions, and parameters like "drop" are actions. If you've trouble telling which is which, a condition-type parameter is something that would require action from an independent source (i.e. the player, you), while an action-type parameter is something that would be dependent on an independent action, or something that necessarily follows from an event taking place.
TL;DR Read it or figure it out yourself. Or preferably, help improve the tutorial by finding a more concise way to explain something without introducing inaccuracy or reducing technical meaning.
In a nutshell, we have covered the basics of configuration, namely the format and how the plugin "thinks" when reading the configuration. We have also done a brief overview of parameters. For more specific and advanced tutorials, please consult the other pages, which are to be listed in the future.