VPCollectables.yml

Vanillaplus has a system of collectables, you are not obliged to use it and if you do not intend to use it then you can ignore this file. Otherwise, you can manage your players' statistics, completions, currency and titles.

'type'_LIST

All collectables are configured under 'type'_LIST following the following rules :

Here you can create an infinite number of collectable but I don't recommend it, firstly because it is not possible to reach such a value, and secondly because your server wouldn't support it either, to make it simple, stay reasonable.

'type'_LIST:
 'storage id':'prefix':
  'id':
    TYPE: BASE
    ALIAS_ID: `alias`
 ...

The name of the node will allow you to choose the different storages you want to use. storage id is the id of the storage as configured in the current plugin VPConfig.yml file. prefix is the prefix for the table to use to create table's name like this : prefix``suffix Nb : The suffix depend on the collectable. If the prefix end with ! or # the name of the table will be only the prefix without the last char.

The id is the id of the collectable, it's a number. Note, for faster save each missing number will be added to the storage table, so try don't skip them. If you have a non-number, 0, lower than 1024 or bigger than 1023 the node will be ignored. ( I think 1023 in a server is large enough, and if you need more you still can use a second storage ). Negative number won't be saved, they are intended to provide session value.

TYPE is the subtype of the collectable.

NAME_PATH is message component path of collectable name, the default path is 'type'.'ALIAS_ID'.NAME.

Example

'type'_LIST:
 VP_Main:VPPlayer_:
  1:
   TYPE: BASE
   ALIAS_ID: alias
 ...

In the example, currencies will be stored using the storage VP_Main in the table VPPlayer_'suffix'.

Currencies

Let's start with the most common one, the currencies. They are intended to support decimals and to be exchanged between players.

Options

Remember to look here to configure the general currency options.

CURRENCY_LIST

The suffix for currency is currency.

BASE

Each BASE currency add theses fields :

SINGLE_PATH is message component path of currency name when single, the default path is CURRENCY.'ALIAS_ID'.SINGLE.

FORMAT_TYPE is number format type. The default format is 0 ( 0 is german, 1 is english, otherwise it's french ).

FORMAT is pattern format. ( see here for more information. ) By default it's ###,###.###, with german type will write number like this : 121.100,14 else if english will be displayed like this : 121,100.14 and in french will be displayed like this 121 100,14

MIN is the minimum value of this currency, by default it's 0 ( note if minimum value is bigger than 0, the default value will be this one. The minimum value stored is -9.999.999.999,999 so it is the minimum allowed ).

STEP is the step amount. Can't be lower than 0,001 ( the default value ). ( Transfert amount, MIN and MAX amount must be a multiple of this value. )

MAX is the maximum value of this currency ( Note, this isn't the max value you could have, just the max value you can win. The maximum value stored is 9.999.999.999,999 so it is the maximum allowed ).

ALLOW_PAY if true, player can pay each other.

USE_SERVER if true, currency limit is the server amount, that allow you to limit the amount of this currency.

Example

CURRENCY_LIST:
 VP_Main:VPPlayer_:
  1:
   #TYPE: BASE
   #NAME: CURRENCY.Coin.NAME
   #SINGLE: CURRENCY.Coin.SINGLE
   ALIAS_ID: Coin
   FORMAT_TYPE: 1
   #FORMAT: "###,###.###"
   #MIN: 0
   #MAX: 9999999999.999
   ALLOW_PAY: true
   #USE_SERVER: false
  2:
   #NAME: CURRENCY.LegendaryCoin.NAME
   #SINGLE: CURRENCY.LegendaryCoin.SINGLE
   ALIAS_ID: LegendaryCoin
   FORMAT_TYPE: 1
   #FORMAT: "###,###"
   #MIN: 0
   #MAX: 9999999999
   STEP: 1
   #ALLOW_PAY: false
   #USE_SERVER: false

Statistics

Let's move on to something more vanilla, a lot of games have some, whether solo, multi, pve or pvp, it's about statistics.

Statistics are very useful in games, whether it's purely for information or for certain mechanics that need to have reached a certain level to advance.

For this reason, VanillaPlus is no exception and offers a complete statistics system that you can use.

Options

Remember to look here to configure the general statistics options.

STAT_LIST

The suffix for currency is stat.

Stat can be integer or decimal, be carefull, they won't be managed the same way by the API.

Type list

BASE

This is the default stat type, will not update without plugin and register as an integer. Don't have additional fields.

Note, if you use multiple server and want load the statistic but not increment it, you can change the type and set it to BASE to disable auto change. ( Like minigame kills, but don't want increment it if kill on survival ). Be carefull, if you use it to replace stat's type the stat you replace must be an integer.

Example

...
 1:
  TYPE : BASE
  NAME_PATH: STAT.1.NAME
  ALIAS_ID: firstStat

BLOCK_BREAK ( Powered )

This one allow you to count block break in real time. Register as a integer.

MATERIAL is the material to count.

ALLOW_GAMEMODE default false, if true will count even if in creative mode.

DECREASE_ON_PLACE default false, if true will decrease the stat when player place the matched material.

Example

...
 2:
  TYPE : BLOCK_BREAK
  ALIAS_ID: breakspawner
  NAME_PATH: STAT.breakspawner.NAME
  MATERIAL: MOB_SPAWNER
  ALLOW_GAMEMODE: false
  DECREASE_ON_PLACE: false

CURRENCY

This one allow you to count the change on player currency, won't work on pay command. Register as a decimal.

CURRENCY_ALIAS is the id of the currency to track.

WIN default true, if true will count the amount player won, else will count the amont he lose.

Example

...
 1:
  TYPE : CURRENCY
  NAME_PATH: STAT.coinWin.NAME
  ALIAS_ID: coinWin
  WIN: true
  CURRENCY_ALIAS: coin

DEATH

This one allow you to count player VanillaPlus death. Register as a integer.

This statistics don't have additional fields.

Example

...
 1:
  TYPE : DEATH
  NAME_PATH: STAT.death.NAME
  ALIAS_ID: death

DOUBLE

This is the default stat type, will not update without plugin and register as a decimal. Don't have additional fields.

Note, if you use multiple server and want load the statistic but not increment it, you can change the type and set it to DOUBLE to disable auto change. ( Like minigame kills, but don't want increment it if kill on survival ).

Example

...
 1:
  TYPE : DOUBLE
  NAME_PATH: STAT.firstStat.NAME
  ALIAS_ID: firstStat

FOOD

This one allow you to count how many VanillaPlus food player eat. Register as a integer.

FOOD is food type defined in Extra.yml file.

Example

...
 1:
  TYPE : FOOD
  NAME_PATH: STAT.napple.NAME
  FOOD: napple
  ALIAS_ID: napple

JOIN

This one allow you to count how many time player join. Register as a integer.

This statistics don't have additional fields.

Example

...
 1:
  TYPE : JOIN
  NAME_PATH: STAT.join.NAME
  ALIAS_ID: join

KILL

This one allow you to count how many kill a player did. Register as a integer.

This statistics don't have additional fields.

Example

...
 1:
  TYPE : KILL
  NAME_PATH: STAT.kill.NAME
  ALIAS_ID: kill

LOAD ( Powered )

This one allow you to count how many time a player has been loaded. Register as a integer.

This statistics don't have additional fields.

Example

...
 1:
  TYPE : LOAD
  NAME_PATH: STAT.load.NAME
  ALIAS_ID: load

MAX ( Powered )

This one allow you to store the highest value a stat reached. Register as the same type as the stat tracked.

This statistics don't have additional fields.

Example

...
 1:
  TYPE : MAX
  NAME_PATH: STAT.topKill.NAME
  ALIAS_ID: topKill
  STAT_ID: kill

MULTI ( Powered )

This one will increase each time one of listed statistics will increment. Register as decimal if track a decimal stat, else as integer.

LISTEN_LIST is list of listened statistics. Note, you can listen statistics created after this one but if their type can change ( like this one ) it may not consider it.

Example

...
 1:
  TYPE : MULTI
  LISTEN_LIST:
   - tmpKillSkeleton
   - tmpKillWSkeleton
  NAME_PATH: STAT.1.NAME
  ALIAS_ID: killSkeletons

PVE_DAMAGE

This one will count pve damage you toke.

FACTOR is a factor for the damages.

USE_DECIMAL Register as integer if false, else register as decimal.

ALLOW_OVERKILL if true will count over kill damages, else will count only took damages.

Example

...
 1:
  TYPE : PVE_DAMAGE
  NAME_PATH: STAT.pveDamage.NAME
  ALIAS_ID: pveDamage
  FACTOR: 5
  USE_DECIMAL: false
  ALLOW_OVERKILL: false

PVP_DAMAGE

This one will count pvp damage you toke.

FACTOR is a factor for the damages.

USE_DECIMAL Register as integer if false, else register as decimal.

ALLOW_OVERKILL if true will count over kill damages, else will count only took damages.

Example

...
 1:
  TYPE : PVP_DAMAGE
  NAME_PATH: STAT.pvpDamage.NAME
  ALIAS_ID: pvpDamage
  FACTOR: 5
  USE_DECIMAL: false
  ALLOW_OVERKILL: false

PVP_DAMAGE_DONE

This one will count pvp damage you dealed.

FACTOR is a factor for the damages.

USE_DECIMAL Register as integer if false, else register as decimal.

ALLOW_OVERKILL if true will count over kill damages, else will count only took damages.

Example

...
 1:
  TYPE : PVP_DAMAGE_DONE
  NAME_PATH: STAT.pvpDone.NAME
  ALIAS_ID: pvpDone
  FACTOR: 5
  USE_DECIMAL: false
  ALLOW_OVERKILL: false

VANILLA ( Free )

This one will use vanilla objectives, the alias will be the objective name.

SCORE_TYPE is the objective type.

Example

...
 1:
  TYPE : VANILLA
  SCORE_TYPE: stat.killEntity.Cow
  NAME_PATH: STAT.1.NAME
  ALIAS_ID: cowkill

Titles

Another new thing that this plugin add, the titles. The titles can serve as a distinction, players want to have the rarest titles which adds lifespan to your server.

You can make unlockable titles with easter egg, free to you to find out how to create them.

Options

Remember to look here to configure the general title options.

TITLE_DISPLAY

Here you can create display icons that can be reused later, mainly for the `TITLE' icon, although other plugins may also use them.

The key is the id to use, can be from 1 to 127. The configuration look like this :

 'key':
   CURRENT: 'icon'
   OWNED: 'icon'
   UNOWNED: 'icon'

CURRENT is the icon returned when it's your current title. OWNED is returned when you own it but isn't your current title. UNOWNED is returned when you don't own this title and it isn't your current one.

Example 1.12.*-

TITLE_DISPLAY:
 1:
  CURRENT: 
   NAME_PATH: TITLE.OWNED_NAME
   DESCRIPTION_PATH:
   - FORMAT.SPACE
   - TITLE.LORE
   - FORMAT.SPACE
   - TITLE.CURRENT
   - FORMAT.SPACE
   ITEM:
    MATERIAL: dye
    DAMAGES: 10
    ENCHANT: 
     DURABILITY : 1
    FLAG_LIST:
     - HIDE_ENCHANTS
  OWNED: 
   NAME_PATH: TITLE.OWNED_NAME
   DESCRIPTION_PATH:
   - FORMAT.SPACE
   - TITLE.LORE
   - FORMAT.SPACE
   - TITLE.OWNED
   - FORMAT.SPACE
   ITEM:
    MATERIAL: dye
    DAMAGES: 10
  UNOWNED: 
   NAME_PATH: TITLE.UNOWNED_NAME
   DESCRIPTION_PATH:
   - FORMAT.SPACE
   - TITLE.LORE
   - FORMAT.SPACE
   - TITLE.UNOWNED
   - FORMAT.SPACE
   ITEM:
    MATERIAL: dye
    DAMAGES: 8

Example 1.13+

TITLE_DISPLAY:
 1:
  CURRENT: 
   NAME_PATH: TITLE.OWNED_NAME
   DESCRIPTION_PATH:
   - FORMAT.SPACE
   - TITLE.LORE
   - FORMAT.SPACE
   - TITLE.CURRENT
   - FORMAT.SPACE
   ITEM:
    MATERIAL: lime_dye
    ENCHANT: 
     DURABILITY : 1
    FLAG_LIST:
     - HIDE_ENCHANTS
  OWNED: 
   NAME_PATH: TITLE.OWNED_NAME
   DESCRIPTION_PATH:
   - FORMAT.SPACE
   - TITLE.LORE
   - FORMAT.SPACE
   - TITLE.OWNED
   - FORMAT.SPACE
   ITEM:
    MATERIAL: lime_dye
  UNOWNED: 
   NAME_PATH: TITLE.UNOWNED_NAME
   DESCRIPTION_PATH:
   - FORMAT.SPACE
   - TITLE.LORE
   - FORMAT.SPACE
   - TITLE.UNOWNED
   - FORMAT.SPACE
   ITEM:
    MATERIAL: light_gray_dye

TITLE_LIST

The suffix for title is title.

BASE

Each BASE title add theses fields :

DESCRIPTION_PATH is the message component for the description ( aka lore ) of the title. The default path is TITLE.'ALIAS_ID'.DESCRIPTION.

LEVEL is the rank level from 1 to 127. If not set will be 1.

SAVE_TIME if true, it will save the date and time it was unlocked, else will only save date. Default value is false. Be careful with this value, if you change it, the database will have to convert the saved data which can be heavy for some.

Example

TITLE_LIST:
 VP_Main:VPPlayer_:
  1:
   NAME_PATH: TITLE.newbie.NAME
   DESCRIPTION_PATH: TITLE.newbie.LORE
   LEVEL: 1
   ALIAS_ID: newbie
   SAVE_TIME: true

Achievements

Now let's finish the collectables with the biggest piece, the success / achievements. They allow you to detect certain actions through statistics to test if a player has the requirement to unlock success / achievements and the rewards associated with it.

ACHIEVEMENT_SETTINGS

Here you can configure options for achievements.

Remember to look here to configure the general title options.

MESSAGE_LIST

Here you can configure the messages sent when a player unlock a message. The message will be sent as a player message.

The key is the level of the achievement.

REQUIREMENT is the requirement to send MESSAGE as message when a player unlock an achivement else will send NO_REQUIREMENT_MESSAGE.

OTHER_REQUIREMENT is the requirement to send OTHER_MESSAGE as message when a player unlock an achivement else will send NO_REQUIREMENT_OTHER_MESSAGE.

OTHER_REQUIREMENT / NO_REQUIREMENT_OTHER_MESSAGE is sent as player message ( in his current channel ) whereas NO_REQUIREMENT_MESSAGE / MESSAGE is sent to the player if online ( I may add an option in the future to disable this security ).

All messages can use %achievement% as placeholder for the achievement name, %achievement_lore% as placeholder for achievement description and sender as [tag] for sender placeholders.

Example

ACHIEVEMENT_SETTINGS:
 MESSAGE_LIST:
  1: 
   REQUIREMENT: "VIP"
   OTHER_REQUIREMENT: "VIP"
   OTHER_MESSAGE: "ACHIEVEMENT.ANNOUNCE_VIP_1"
   NO_REQUIREMENT_OTHER_MESSAGE: "ACHIEVEMENT.ANNOUNCE_1"
   MESSAGE: "ACHIEVEMENT.SELF_VIP_1"
   NO_REQUIREMENT_MESSAGE: "ACHIEVEMENT.SELF_1"

ACHIEVEMENT_DISPLAY

Here you can create display icons that can be reused later, mainly for the `ACHIEVEMENT' icon, although other plugins may also use them.

The key is the id to use, can be from 1 to 127. The configuration look like this :

 'key':
   CURRENT: 'icon'
   OWNED: 'icon'
   UNOWNED: 'icon'

OWNED is returned when you unlocked it. UNOWNED is returned when you didn't unlocked it.

Example 1.12.*-

ACHIEVEMENT_DISPLAY:
 1:
  OWNED:
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.OWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.OWNED_DESCRIPTION
   ITEM: 
    MATERIAL: wool
    DAMAGES: 5
  UNOWNED: 
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.UNOWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.UNOWNED_DESCRIPTION
   ITEM:
    MATERIAL: wool
    DAMAGES: 8
 2:
  OWNED:
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.OWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.OWNED_DESCRIPTION
   ITEM: 
    MATERIAL: dye
    DAMAGES: 10
  UNOWNED: 
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.UNOWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.UNOWNED_DESCRIPTION
   ITEM:
    MATERIAL: dye
    DAMAGES: 8
 3:
  OWNED:
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.OWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.OWNED_DESCRIPTION
   ITEM: 
    MATERIAL: dye
    DAMAGES: 10
  UNOWNED: 
   TYPE: BASE
   IS_STATIC: false
   NAME_PATH: ACHIEVEMENT.UNOWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.UNOWNED_DESCRIPTION2
   ITEM:
    MATERIAL: dye
    DAMAGES: 8

Example 1.13+

ACHIEVEMENT_DISPLAY:
 1:
  OWNED:
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.OWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.OWNED_DESCRIPTION
   ITEM: lime_wool
  UNOWNED: 
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.UNOWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.UNOWNED_DESCRIPTION
   ITEM: light_gray_wool
 2:
  OWNED:
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.OWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.OWNED_DESCRIPTION
   ITEM: lime_dye
  UNOWNED: 
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.UNOWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.UNOWNED_DESCRIPTION
   ITEM: light_gray_dye
 3:
  OWNED:
   TYPE: BASE
   NAME_PATH: ACHIEVEMENT.OWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.OWNED_DESCRIPTION
   ITEM: lime_dye
  UNOWNED: 
   TYPE: BASE
   IS_STATIC: false
   NAME_PATH: ACHIEVEMENT.UNOWNED_NAME
   DESCRIPTION_PATH: ACHIEVEMENT.UNOWNED_DESCRIPTION2
   ITEM: light_gray_dye

ACHIEVEMENT_LIST

The suffix for title is achievement.

BASE

Each BASE title add theses fields :

DESCRIPTION_PATH is the message component for the description ( aka lore ) of the achievement. The default path is ACHIEVEMENT.'ALIAS_ID'.DESCRIPTION.

LEVEL is the rank level from 1 to 127. If not set will be 1.

SAVE_TIME if true, it will save the date and time it was unlocked, else will only save date. Default value is false. Be careful with this value, if you change it, the database will have to convert the saved data which can be heavy for some.

ANNOUNCE should this achievement be announced ? If true will use the message with this LEVEL, else won't send message.

LISTEN_LIST is a list of stat's alias listened. That mean if a player's stat with this id update that'll try unlock this achievement.

REQUIREMENT is the requirement required to unlock this achievement.

REWARD is the reward for unlocked this achievement.

Example

ACHIEVEMENT_LIST:
 VP_Main:VPPlayer_:
  1:
   NAME_PATH: ACHIEVEMENT.newbie.NAME
   DESCRIPTION_PATH: ACHIEVEMENT.newbie.LORE
   LEVEL: 1
   ALIAS_ID: newbie
   SAVE_TIME: true
   ANNOUNCE: true
   LISTEN_LIST:
   - newbie
   REQUIREMENT:
    TYPE: STAT
    ALIAS_ID: newbie
    AMOUNT: 1
    KEEP: true
    RESET: false
    FORMAT: REQUIREMENT.STAT_1
   REWARD:
    coin:
     TYPE: CURRENCY
     ALIAS_ID: coin
     AMOUNT: 100
    title:
     TYPE: TITLE
     ALIAS_ID: newbie