5. Reward Triggers and Items - obzidi4n/delphivote GitHub Wiki

Creating a unique experience for your players is the great strength of DelphiVote.

Want to rain diamonds on first-time voters? Done. Fancy a server-wide party every 100 votes? You got it! Mix and match rewards, set them to trigger whenever you want - every vote, milestone votes, or even on a loop. You can even surprise every player who's ever logged in! It's like having a vote-reward playground where you make the rules.

Vote Rewards are defined using a combination of settings from reward_triggers.yml and reward_items.yml:

Reward Triggers

Reward Triggers define when rewards are given out, and who gets them.

# reward_triggers.yml

trigger_id:                  (required, string with underscores, must be unique)
  trigger_name:               (required, string)
  trigger_user:               (required, string, must be 'player' or 'server'. Defines who receives the rewards)
  trigger_threshold:          (required, integer. Number of votes required to fire the trigger. 0 = fires on every vote.)
  trigger_repeat:             (required, true/false. Should the trigger fire every time trigger_threshold is met.)
  trigger_rewards:             
  - reward_id:                (required, corresponds to any item from reward_items.yml)
    reward_id:                (another item from reward_items.yml, add as many as you want)
  trigger_player_message:     (optional, string, message to send to the player who voted)
  trigger_broadcast_message:  (optional, string, message to send to all players)

Example: Player Vote

Here's a simple Reward Trigger you would define in reward_triggers.yml to give every player a diamond_pack reward every time they vote, along with custom player and server messages:

# reward_triggers.yml

player_vote:
  trigger_name: Standard Player Vote
  trigger_user: player
  trigger_threshold: 0
  trigger_repeat: true
  trigger_rewards:
  - diamond_pack
  trigger_player_message: '&aThanks for voting, {player}! You now have {votes} votes.'
  trigger_broadcast_message: '&b{player} just voted on {service} and now has {votes} votes!'

Example: 100-Vote Server Party

And here's a sample trigger that sends out a server_celebration_pack reward to all players in the database, every time the server accumulates another 100 votes:

# reward_triggers.yml

server_milestone_100:
  trigger_name: Server 100-Vote Milestone
  trigger_user: server
  trigger_threshold: 100
  trigger_repeat: true
  trigger_rewards:
  - server_celebration_pack
  trigger_player_message: '&aYou''ve received a Server Celebration reward!'
  trigger_broadcast_message: '&aThe server has received another 100 votes! Time to celebrate!'

Available placeholders for trigger messages:

{player} - The name of the player who voted
{votes} - The total number of votes for the player
{service} - The name of the voting service

Be sure to enclose strings in quotes ('') if they contain special formatting codes such as & or hex colors.

Reward Items

Reward Items can include any number of standard or customized Minecraft items, HeadDatabase blocks or console commands. Custom lore and messaging can be set for every reward item, and collections of items can be randomized for additional variety!

# reward_items.yml

reward_id:       (required, string with underscores, must be unique.)
  reward_name:   (required, string)
  reward_items:  (required, list of items to give)
  - item:        (required, valid minecraft item name or Head Database ID starting with 'hdb-')
    quantity:    (required, integer greater than 0)
    title:       (optional, string)
    lore:        (optional, list of strings)
    commands:    (optional, list of console commands to execute when the item is given, can use {player} placeholder for the player's name)
 reward_randomized:  (optional, true/false. If true, the item order will be randomized)
 reward_max_items:   (optional, integer. 0 grants all items. Use along with reward_randomized to create variety of rewards)

Example: Diamond Pack

Here's a simple reward activated by our player_vote trigger (above) that gives a player a Diamond and some short-term enchantment boosts:

# reward_items.yml

diamond_pack:
  reward_name: Diamond and Speed Boosts
  reward_items:
  - title: Vote Diamond
    item: DIAMOND
    quantity: 1
    lore:
    - Thank you for voting!
    - '&aKeep voting for special rewards!'
  - title: Console Command
    item: AIR
    quantity: 1
    commands:
    - effect give {player} minecraft:speed 5 1 true
    - effect give {player} minecraft:jump_boost 5 1 true
  reward_randomized: false
  reward_max_items: 0

Example: Server Celebration Pack

Here's a more complex reward configuration activated by our server_milestone_100 trigger (above) that goes out to every player in the database. We take advantage of the reward_randomized and reward_max_items settings to shuffle and grant different combinations of items to individual players! More reward_items could be added to this list without limit:

# reward_items.yml

server_celebration_pack:
  reward_name: Random Rewards for Everyone
  reward_items:
  - title: Celebration Firework
    item: FIREWORK_ROCKET
    quantity: 16
    lore:
    - Let's celebrate our server milestone!
  - title: Celebration Cake
    item: CAKE
    quantity: 1
    lore:
    - A delicious cake for everyone!
  - title: Warrior's Blade
    item: DIAMOND_SWORD
    quantity: 1
    lore:
    - A powerful sword for your battles.
    - title: Miner's Friend
    item: IRON_PICKAXE
    quantity: 1
    lore:     
    - An enchanted pickaxe for your mining adventures.
  - title: Golden Delight
    item: GOLDEN_APPLE
    quantity: 3
    lore:
    - A golden apple to keep you healthy.
  reward_randomized: true
  reward_max_items: 3