ecoCreature

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.

PermissionDescription
ecocreature.gain.group: falseEnables gain multiplier based on group
ecocreature.gain.time: falseEnables gain multiplier based on time period
ecocreature.gain.environment: falseEnables gain multiplier based on environment
ecocreature.gain.heroes: falseEnables gain multiplier based on Heroes party status
ecocreature.gain.mobarena: falseEnables gain multiplier based on player arena status
ecocreature.gain.worldguard: falseEnables gain multiplier based on WorldGurad region
ecocreature.reward.angrywolf: falseEnables rewards for angry wolves
ecocreature.reward.blaze: falseEnables rewards for blazes
ecocreature.reward.cavespider: falseEnables rewards for cave spiders
ecocreature.reward.chicken: falseEnables rewards for chickens
ecocreature.reward.cow: falseEnables rewards for cows
ecocreature.reward.creeper: falseEnables rewards for creepers
ecocreature.reward.custom: falseEnables rewards for custom sets
ecocreature.reward.deathpenalty: falseEnables penalty for playe death
ecocreature.reward.deathstreak: falseEnables penalty for death streaks via DeathTpPlus
ecocreature.reward.enderdragon: falseEnables rewards for enderdragons
ecocreature.reward.enderman: falseEnables rewards for endermen
ecocreature.reward.ghast: falseEnables rewards for ghasts
ecocreature.reward.giant: falseEnables rewards for giants
ecocreature.reward.killstreak: falseEnables rewards for kill streaks via DeathTpPlus
ecocreature.reward.magmacube: falseEnables rewards for magmacubes
ecocreature.reward.monster: falseEnables rewards for monsters
ecocreature.reward.mushroomcow: falseEnables rewards for mushroomcows
ecocreature.reward.ozelot: falseEnables rewards for ozelot
ecocreature.reward.pig: falseEnables rewards for pigs
ecocreature.reward.pigzombie: falseEnables rewards for pig zombies
ecocreature.reward.player: falseEnables rewards for players (a.k.a. PVP reward)
ecocreature.reward.poweredcreeper: falseEnables rewards for powered creepers
ecocreature.reward.sheep: falseEnables rewards for sheep
ecocreature.reward.silverfish: falseEnables rewards for silverfish
ecocreature.reward.skeleton: falseEnables rewards for skeletons
ecocreature.reward.slime: falseEnables rewards for slime
ecocreature.reward.snowman: falseEnables rewards for snowmen
ecocreature.reward.spawner: falseEnables rewards for spawners
ecocreature.reward.spider: falseEnables rewards for spiders
ecocreature.reward.squid: falseEnables rewards for squid
ecocreature.reward.villager: falseEnables rewards for villagers
ecocreature.reward.villagergolem: falseEnables rewards for villagergolems
ecocreature.reward.wolf: falseEnables rewards for wolves
ecocreature.reward.zombie: falseEnables 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

OptionDescription
IntegerCurrency: falseRound reward amounts to the nearest integer.

Hunting

OptionDescription
AllowCamping: falseGive rewards for mob spawner camping.
ClearCampDrops: trueClear drops from mobs killed near spawners.
CampingByDistance: trueDetermine camping by closeness to spawner
CampingByEntity: falseDetermine camping by remembering entities spawned by mobspawners.
CampRadius: 7If CampingByDistance is true, then this is how many blocks away from a spawner
you need to be to get a reward
ClearDefaultDrops: falseWhen 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: trueReplace instead of stack rewards drops/items.
FixedDrops: falseDo not randomize amount of drop items. Always drop a fixed amount.
BowRewards: trueEnable rewards for mobs killed with bow & arrow.
AllowUnderSeaLVL: trueEnable rewards for killing mobs under sea level.
WolverineMode: trueEnable rewards for kills with tamed creatures (wolves).
PenalizeDeath: falsePenalize players when they die.
PenalizeType: trueWhen set to true, PenalizeAmount is used as a percentage. When set to false,
PenalizeAmount is used as a fixed amount.
PenalizeAmount: 0.05This value represents a percentage or a fixed amount depending on the
PenalizeType setting.
NoFarm: falseRemove drops from mobs killed by farming contraptions (mob death by cacti,
falling, drowning or suffocation).
NoFarmFire: falseRemove drops from mobs killed by fire.
MobArenaRewards: falseAllows rewards when players are in the arena.

Messages

OptionDescription
Output: trueEnable all reward messages.
NoReward: trueMessage players when they get no reward for a kill.
Spawner: falseMessage 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/TokenDescription
&[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.