Documentation
ecoCreature Documentation
What is ecoCreature?
ecoCreature is a Bukkit plugin that allows you to customize coin rewards/penalties, Experience Orbs and item drops for mobs and PvP. Customization includes randomization of coin, Exp Orbs and item amounts as well as enchantment levels on items.
Features
- Coin rewards/penalties for mobs and PvP
- Custom experience orb amounts
- Custom item drops (w/enchantments) and drop amounts for mobs and PvP
- Custom reward messaging.
- Prevent camping around mob spawners.
- Prevent mob farming.
- Prevent rewards through use of bow and arrow.
- Multiply coin rewards based group, time or environment.
- Multi-world support.
Installation
Requirements
ecoCreature requires the Vault plugin to be installed. This plugin allows ecoCreature to support a wide variety of Permissions and Economy plugins. See the Vault home page for more information.
Basic Installation
- Step 1:
Download the latest version of ecoCreature and copy to plugins directory.
- Step 2:
Download the latest version of Vault and copy it plugins directory.
- Step 3:
Add permissions:
# NOTE: This can vary depending on what permission plugin is in use. # Consult the documentation for your particular permission plugin # for the correct syntax. default: permissions: ecocreature.reward.*: true ecocreature.gain.*: true
- Step 4:
Start/Restart your server and you're done! Consult the Configuration section below to find out how to customize your installation.
Optional Installation
- Economy:
Installation of an Economy plugin is required to enable coin rewards. Consult the Vault home page so find out which Economy plugins are supported.
- HeroicDeath2 (a.k.a. DeathTpPlus "Classic"):
Installation of this special version of the DeathTpPlus plugin enables rewards for kill and death streaks. Consult the Configuration section below for more information on how to configure the rewards.
Permissions
Basic
If you just want to enable all rewards and gain multipliers, add this to your permissions:
## enable everything ## ecocreature.reward.*: true ecocreature.gain.*: true
Advanced
If you prefer to have more control over the rewards, refer to the table below for available permissions.
Permission | Description |
ecocreature.gain.group: false | Enables gain multiplier based on group |
ecocreature.gain.time: false | Enables gain multiplier based on time period |
ecocreature.gain.environment: false | Enables gain multiplier based on environment |
ecocreature.gain.heroes: false | Enables gain multiplier based on Heroes party status |
ecocreature.gain.mobarena: false | Enables gain multiplier based on player arena status |
ecocreature.gain.worldguard: false | Enables gain multiplier based on WorldGurad region |
ecocreature.reward.angrywolf: false | Enables rewards for angry wolves |
ecocreature.reward.blaze: false | Enables rewards for blazes |
ecocreature.reward.cavespider: false | Enables rewards for cave spiders |
ecocreature.reward.chicken: false | Enables rewards for chickens |
ecocreature.reward.cow: false | Enables rewards for cows |
ecocreature.reward.creeper: false | Enables rewards for creepers |
ecocreature.reward.custom: false | Enables rewards for custom sets |
ecocreature.reward.deathpenalty: false | Enables penalty for playe death |
ecocreature.reward.deathstreak: false | Enables penalty for death streaks via DeathTpPlus |
ecocreature.reward.enderdragon: false | Enables rewards for enderdragons |
ecocreature.reward.enderman: false | Enables rewards for endermen |
ecocreature.reward.ghast: false | Enables rewards for ghasts |
ecocreature.reward.giant: false | Enables rewards for giants |
ecocreature.reward.killstreak: false | Enables rewards for kill streaks via DeathTpPlus |
ecocreature.reward.magmacube: false | Enables rewards for magmacubes |
ecocreature.reward.monster: false | Enables rewards for monsters |
ecocreature.reward.mushroomcow: false | Enables rewards for mushroomcows |
ecocreature.reward.ozelot: false | Enables rewards for ozelot |
ecocreature.reward.pig: false | Enables rewards for pigs |
ecocreature.reward.pigzombie: false | Enables rewards for pig zombies |
ecocreature.reward.player: false | Enables rewards for players (a.k.a. PVP reward) |
ecocreature.reward.poweredcreeper: false | Enables rewards for powered creepers |
ecocreature.reward.sheep: false | Enables rewards for sheep |
ecocreature.reward.silverfish: false | Enables rewards for silverfish |
ecocreature.reward.skeleton: false | Enables rewards for skeletons |
ecocreature.reward.slime: false | Enables rewards for slime |
ecocreature.reward.snowman: false | Enables rewards for snowmen |
ecocreature.reward.spawner: false | Enables rewards for spawners |
ecocreature.reward.spider: false | Enables rewards for spiders |
ecocreature.reward.squid: false | Enables rewards for squid |
ecocreature.reward.villager: false | Enables rewards for villagers |
ecocreature.reward.villagergolem: false | Enables rewards for villagergolems |
ecocreature.reward.wolf: false | Enables rewards for wolves |
ecocreature.reward.zombie: false | Enables rewards for zombies |
Configuration
All customization is done by editing the plugins/ecoCreature/default.yml configuration file. For those who are impatient, the default.yml file already contains documentation in-line if want to dive in right away. A description of each of the options contained in the configuration file is also listed below.
System Section
The System section of the default.yml configuration file are global rules on how rewards and penalties are given. This section also includes settings for global messages and an option for integer based economy plugins.
The three subsections of System, which are Economy, Hunting and Messages, are described below with default values.
Economy
Option | Description |
IntegerCurrency: false | Round reward amounts to the nearest integer. |
Hunting
Option | Description |
AllowCamping: false | Give rewards for mob spawner camping. |
ClearCampDrops: true | Clear drops from mobs killed near spawners. |
CampingByDistance: true | Determine camping by closeness to spawner |
CampingByEntity: false | Determine camping by remembering entities spawned by mobspawners. |
CampRadius: 7 | If CampingByDistance is true, then this is how many blocks away from a spawner you need to be to get a reward |
ClearDefaultDrops: false | When mobs are killed by a player, remove the default drops. If you enable this, you can no longer stack the reward drops on top of the default drops when OverrideDrops is set to true. |
OverrideDrops: true | Replace instead of stack rewards drops/items. |
FixedDrops: false | Do not randomize amount of drop items. Always drop a fixed amount. |
BowRewards: true | Enable rewards for mobs killed with bow & arrow. |
AllowUnderSeaLVL: true | Enable rewards for killing mobs under sea level. |
WolverineMode: true | Enable rewards for kills with tamed creatures (wolves). |
PenalizeDeath: false | Penalize players when they die. |
PenalizeType: true | When set to true, PenalizeAmount is used as a percentage. When set to false, PenalizeAmount is used as a fixed amount. |
PenalizeAmount: 0.05 | This value represents a percentage or a fixed amount depending on the PenalizeType setting. |
NoFarm: false | Remove drops from mobs killed by farming contraptions (mob death by cacti, falling, drowning or suffocation). |
NoFarmFire: false | Remove drops from mobs killed by fire. |
MobArenaRewards: false | Allows rewards when players are in the arena. |
Messages
Option | Description |
Output: true | Enable all reward messages. |
NoReward: true | Message players when they get no reward for a kill. |
Spawner: false | Message players for camping spawners. |
NoCampMessage: '&7You find no rewards camping monster spawners.' | Custom message for no camping mob spawners. |
NoBowMessage: '&7You find no rewards on this creature.' | Custom message for no rewards killing with bow & arrow. |
DeathPenaltyMessage: '&7You wake up to find &6<amt>&7 missing from your pockets!' | Custom message for death penalty. |
Gain Section
The Gain section of the default.yml file controls gain multipliers for coin rewards. You can multiply by permission group, in-game time period and the type of world environment. The gain formula used is as follows:
total_reward = group * reward + time * reward + env * reward
Groups
If you have a permission plugin that supports groups, you can enter the group names in the Groups section along with the gain Amount to be used in the gain formula. Below is an example of no gain for the Default group, while another group named Donors get coin rewards doubled.
Gain: Groups: Default: Amount: 1.0 Donors: Amount: 2.0
Time
You can adjust the gain amount depending on the in-game time period. There are six time periods available. Below is an example where the gain increases between Dusk and Dawn.
Gain: Time: Sunrise: Amount: 1.0 Day: Amount: 1.0 Sunset: Amount: 1.0 Dusk: Amount: 1.125 Night: Amount: 1.25 Dawn: Amount: 1.125
Environment
You can adjust the gain amount depeding on the type of world a reward is given. The types of worlds available are Normal, Nether and The End. Below is an example of no gain for Normal and increased gain for Nether and The End.
Gain: Environment: Normal: Amount: 1.0 Nether: Amount: 1.125 The_End: Amount: 1.25
RewardTable Section
The RewardTable section defines rewards for all the supported entity types. For each entity type, you can define the drops, coin amount, exp orbs and messages.
It's important to note that you do not need to define a reward for every entity type. You only need to define rewards for the entities that interest you. Furthermore, you do not need to specify every option for a reward. You only need to define the options that interest you.
Entity Types
- AngryWolf
- Blaze
- CaveSpider
- Chicken
- Cow
- Creeper
- Enderman
- Ghast
- Giant
- MagmaCube
- Monster
- MushroomCow
- Ozelot
- Pig
- PigZombie
- Player
- PoweredCreeper
- Sheep
- Silverfish
- Skeleton
- Slime
- Snowman
- Spawner
- Spider
- Squid
- Villager
- VillagerGolem
- Wolf
- Zombie
HeroicDeath2 Entity Types (Optional)
If you install the HeroicDeath2 plugin, you can define rewards for death and kill streaks with DeathStreak and KillStreak entities. See the Special Entities section below for more information.
- DeathStreak
- KillStreak
Drops
Syntax
The syntax for entries in the Drops section is as follows:
# Example item RewardTable: Cow: Drops: - 'ITEM_ID:[MIN_QTY-]MAX_QTY:CHANCE' # Example item with Data ID (e.g. colors for wool, leaf types, etc.) RewardTable: Cow: Drops: - 'ITEM_ID.DATA_ID:[MIN_QTY-]MAX_QTY:CHANCE' # Example item with Data ID and durability RewardTable: Cow: Drops: - 'ITEM_ID.DATA_ID.DURABILITY:[MIN_QTY-]MAX_QTY:CHANCE' # Example item with an Enchantment RewardTable: Cow: Drops: - 'ITEM_ID,ENCHANTMENT.[MIN_LVL-]MAX_LVL:[MIN_QTY-]MAX_QTY:CHANCE' # Example item with more than one Enchantment RewardTable: Cow: Drops: - 'ITEM_ID,ENCHANTMENT.[MIN_LVL-]MAX_LVL,ENCHANTMENT.[MIN_LVL-]MAX_LVL:[MIN_QTY-]MAX_QTY:CHANCE'
You can find a list of available ITEM_IDs here.
To help better understand the Drop syntax, we'll start with a simple drop and build on it in the examples that follow below.
Basic Example
Let's start with a simple drop - a diamond sword:
RewardTable: Cow: Drops: - 'diamond_sword:2:25'
In the above example, 0 to 2 diamond swords drop 25% of the time. If you never want zero swords to drop, you can specify a range:
RewardTable: Cow: Drops: - 'diamond_sword:1-2:25'
Now we have 1 to 2 diamond swords dropping %25 of the time. If you always want a fixed amount to drop, there are two methods.
The first method is done by setting the global System flag FixedDrops to true. The second method is as follows:
RewardTable: Cow: Drops: - 'diamond_sword:2-2:25'
The above method provides more flexibility over the global FixedDrops flag.
Durability Example
If you want to drop a worn diamond sword, you need to specify the durability:
RewardTable: Cow: Drops: - 'diamond_sword..781:1-2:25'
The two dots is not a typo. We purposely left our the Data ID (see next section) since we only want to specify the durability of the item. More information on durability can be found here.
Data ID Example
Let's add another item to our drops - a potion:
RewardTable: Cow: Drops: - 'diamond_sword..781:1-2:25' - 'potion.2:1:25'
Note that the potion has an associated Data ID that defines the type of potion. In our case, a Data ID of 2 corresponds to "Swiftness". A complete listing of Data IDs for all items can be found here.
Enchantment Example
Next, let's add an enchantment to our diamond sword:
RewardTable: Cow: Drops: - 'diamond_sword..781,damage_all.4:1-2:25' - 'potion.2:1:25'
The enchantment damage_all.4 corresponds to "Sharpness IV". If you want to randomize the level instead of being fixed at 4, do the following:
RewardTable: Cow: Drops: - 'diamond_sword..781,damage_all.0-4:1-2:25' - 'potion.2:1:25'
Now we have a random enchantment level range of 0 to 4. In the case where the level turns out to be 0, the enchantment is removed.
You can also apply more than one enchantment to an item, separated by commas:
RewardTable: Cow: Drops: - 'diamond_sword..781,damage_all.0-4,fire_aspect.0-2:1-2:25' - 'potion.2:1:25'
A list of valid enchantments can be found here.
Coin
Coin rewards have a percentage chance of dropping and a random range for the amount.
Example
Here's an example of 50% chance for coin reward with a random range of 0 to 10:
RewardTable: Cow: Coin_Minimum: 0.0 Coin_Maximum: 10.0 Coin_percent: 50.0
If you don't want a rand range, set the min/max to the same value:
RewardTable: Cow: Coin_Minimum: 10.0 Coin_Maximum: 10.0 Coin_percent: 50.0
Penalty Example
For penalties, the min/max values should range in negative values. Here's an example of a penalty ranging from -10 to 0:
RewardTable: Cow: Coin_Minimum: 10.0 Coin_Maximum: 10.0 Coin_percent: 50.0
Experience Orbs
Experience orbs are similar to coin rewards. You can specify a percentage chance and a random range for the amount.
This is an example of getting 0 to 10 orbs 50% of the time:
RewardTable: Cow: ExpMin: 0 ExpMax: 10 ExpPercent: 50.0
And now an example of a fixed amount of 10 orbs 50% of the time:
RewardTable: Cow: ExpMin: 10 ExpMax: 10 ExpPercent: 50.0
Messages
You can stick with the default messages or you can customize them per reward. Messages can be customized with color codes and tokens:
Color codes & replacement tokens:
Code/Token | Description |
&[0-9,a-f,k,l,m,n,o,r] | Color codes |
<plr> | Display player name in a message |
<crt> | Display creature name in a message |
<amt> | Display amount in a message |
<itm> | Display item used to kill in a message |
Example
An example using colors and tokens:
RewardTable: Cow: NoReward_Message: '&7You slayed a &5<crt>&7 using a &3<itm>.' Reward_Message: '&7You are awarded &6<amt>&7 for slaying a &5<crt>.' Penalty_Message: '&7You are penalized &6<amt>&7 for slaying a &5<crt>.'
Special Reward Entities
Player
Player: # # IMPORTANT NOTE: If you define Drops, and OverrideDrops is set to true, # the victim's inventory is be replaced! Also note that the amount # awarded is taken from the victim. Coin_Minimum: 5.00 Coin_Maximum: 10.50 Coin_Percent: 50.0 NoReward_Message: '' Reward_Message: '&7You are awarded &6<amt>&7 for murdering &5<crt>&7.' Penalty_Message: '&7You are penalized &6<amt>&7 for murdering &5<crt>&7.'
DeathStreak
DeathStreak: # # This reward requires DeathTpPlus "classic": http://tiny.cc/heroicdeath2. # The penalty amount is multiplied by the number of deaths in the streak. Coin_Minimum: -1.00 Coin_Maximum: -1.00 Coin_Percent: 100.00 NoReward_Message: '' Reward_Message: '&7You earned &6<amt>&7 for that death streak!' Penalty_Message: '&7That death streak cost you &6<amt>&7.'
KillStreak
KillStreak: # # This reward requires DeathTpPlus "classic": http://tiny.cc/heroicdeath2. # The reward amount is multiplied by the number of kills in the streak. Drops: - 'diamond:1:100' Coin_Minimum: 2.00 Coin_Maximum: 2.00 Coin_Percent: 100.00 NoReward_Message: '' Reward_Message: '&7You earned &6<amt>&7 for that kill streak!' Penalty_Message: '&7That kill streak cost you &6<amt>&7.'
RewardSets Section
RewardSets: ############################################################################ # Drop set examples ############################################################################ # Drop sets allow you to define groups or sets of drops for use in the # RewardTable. The most obvious benefit is that you no longer have to copy # and paste a list of common drops. You can also get really creative with # different combinations of sets. # # Example: # MySetName: # Drops: # - 'diamond:5:50' # - 'leaves.2:1-2:100' # Coin_Minimum: 0.0 # Coin_Maximum: 10.0 # Coin_percent: 50.0 # ExpMin: 0 # ExpMax: 10 # ExpPercent: 50.0 # # See how the these example sets below are used for Zombies in the # RewardTable ############################################################################ NormalZombie: Drops: - 'rotten flesh:2:75' FarmerZombie: Drops: - 'rotten flesh:2:75' - 'diamond_pickaxe,durability.0-3:1:25' Coin_Minimum: 1.00 Coin_Maximum: 3.50 Coin_Percent: 50.0 WarriorZombie: Drops: - 'rotten flesh:2:75' - 'diamond_sword,damage_all.0-4:1:25' Coin_Minimum: 1.00 Coin_Maximum: 3.50 Coin_Percent: 50.0 ExpMin: 0 ExpMax: 10 ExpPercent: 50.0
RewardTable: Zombie: Sets: - NormalZombie - FarmerZombie - WarriorZombie
Multiworld Configuration
Use multiworld configuration only if you want different settings for a particular world. If you want the same settings for all of your worlds, you do not need multiworld configuration.
Multiworld support is accomplished by copying default.yml into the plugins/ecoCreature/worlds directory and renaming it to match your world name.
For example, if you have a setup with three worlds, named world1, world2 and world3, and wanted to customize world3 while leaving world1 and world2 with default settings:
- Step 1:
Copy plugins/ecoCreature/default.yml to plugins/ecoCreature/worlds/world3.yml
- Step 2:
Customize world3 by editing plugins/ecoCreature/worlds/world3.yml
- Step 3:
Restart your server
If you want to have separate settings for each world
FAQs
- Q: Do I need to have an entry in the RewardTable for every type of mob in the game?
- A: No. Add only the mobs you want to drop rewards.
- Q: Where can I find a list of valid item names?
- A: here
- Q: Where can I find a list of valid enchantment names?
- A: here
Getting Help
For support, you can visit the forums. Most problems are usually from misconfiguration so it is always helpful to post your current configuration using pastie.org instead cluttering up the forums with a giant post.
Reporting Bugs
However, if you do find a reproducible bug, you can file a ticket on GitHub. Make sure to includes steps on how to reproduce the bug as well as posting any error messages from the server.log using pastie.org.
Source
You can also find the source code for ecoCreature on GitHub.