Configuring Race Triggers and Conditions

In this next section, you will be learning how to define race triggers and conditions, as well as how to customize the passives you get upon using them. You can also set conditions, which need to pass in order for the trigger to work. One example is checking if a player is currently standing on a grass block and giving them a speed passive. You can also use trigger passives to allow players to actually "level up" their race.

This is arguably one of the most powerful parts of the entire plugin, so it is recommended you

For this tutorial, we will be picking up from the Configuring Race Items page for consistency reasons. Adding race triggers is quite simple and can be quite powerful. Below you can view a list of the currently existing triggers.

Anything surrounded with < or > means that a value must be specified. Anything surrounded with ( or ) means the value is optional but not required.

Trigger List

Trigger Name	Description	Usage
block-break	Trigger for when a block is broken.	block-break (block)
block-place	Trigger for when a block is placed.	block-place (block)
block-relative	Trigger for when a block is relative to a player.	block-relative (See: BlockFace)
breed-animal	Trigger for when you breed animals.	breed-animal (animal)
burn	Trigger for when you burn.	burn
consume-item	Trigger for when you consume (or eat) an item.	consume-item (item)
craft-item	Trigger for when you craft an item.	craft-item (item)
damage-entity	Trigger for when you damage an entity.	damage-entity (entity)
damage-mythicmob	Trigger for when you damage a MythicMob. (Requires MythicMobs.)	damage-mythicmob (mythicmob)
day	Trigger than runs when it is day.	day
death	Trigger for when you die.	death
element-buy	Trigger for when you buy an element.	element-buy (See: Configuring Race Skilltree Unlockables)
enchant-item	Trigger for when you enchant an item	enchant-item (item)
fly	Trigger for when you start flying.	fly
fish	Trigger for when you fish.	fish (caught item)
health-regen	Trigger for when you regen health.	health-regen
in-moonlight	Trigger for when you're in the moonlight.	in-moonlight
in-region	Trigger for when you're in a WorldGuard region.	in-region
in-sunlight	Trigger for when you're in the sunlight.	in-sunlight
in-world	Trigger for when you're in a specific world.	in-world
inside	Trigger for when you're inside.	inside
join	Trigger for when you join.	join
kill-entity	Trigger for when you kill an entity.	kill-entity (entity)
kill-mythicmob	Trigger for when you kill a MythicMob. (Requires MythicMobs.)	kill-mythicmob (mythicmob)
killed-by	Trigger for when you're killed by a mob or a race.	killed-by <mob/race name>
launch-projectile	Trigger for when you launch a projectile.	launch-projectile (projectile)
move	Trigger for when you move.	move
night	Trigger that runs when it's night.	night
outside	Trigger that runs when you're outside.	outside
quit	Trigger for when you quit.	quit
race-levelup	Trigger for when you level up.	race-levelup (level)
race-change	Trigger for when you change races.	race-change (race)
race-leveldown	Trigger for when you level down.	race-leveldown (level)
race-exp-gain	Trigger for when you gain experience.	race-exp-gain (exp)
race-exp-lose	Trigger for when you lose experience.	race-exp-lose (exp)
reclaim-race-items	Trigger for when you reclaim your race items.	reclaim-race-items
reclaim-skillpoints	Trigger for when you reclaim your skillpoints.	reclaim-skillpoints
sneak	Trigger for when you sneak.	sneak
stop-fly	Trigger for when you stop flying.	stop-fly
stop-sneak	Trigger for when you stop sneaking.	stop-sneak
take-damage	Trigger for when you take damage.	take-damage (entity)
tame-animal	Trigger for when you tame an animal.	tame-animal (animal)
teleport	Trigger for when you teleport.	teleport
ticks	Trigger that runs every x amount of ticks.	ticks

For race triggers, there are a handful of options you can define. Here are the currently existing options you can set.

Option Name	Description	Input	Default
delay	The delay (in seconds) between each time the trigger runs.	int	0
chance	The chance the trigger will run.	int	100
run-passives	The passives to run (see below)	string list	empty
conditions	The conditions to check (see below)	string list	empty

Passives

With triggers, you can also define passives that will run when you use the trigger. See below for a list of passives.

Passive Name	Description	Usage
add-potion-effect	Add a potion effect.	add-potion-effect
allow-flight	Sets if flight should be allowed	allow-flight (true/false)
burn	Burn the player.	burn
damage	Damage the player.	damage
disguise	Disguise a player (requires LibsDisguises).	disguise
drop-item	Drop an item at the players location.	drop-item <item (can be race item or one-lined item)>
give-exp	Give the player experience.	give-exp
give-health	Give the player health.	give-health
give-race-exp	Give race experience (See: Configuring Race Levels)	give-race-exp
give-saturation	Give saturation (food) levels to the player.	give-saturation
reapply-attributes	Reapplies and refreshes the attributes.	reapply-attributes (if temporary attributes should be cleared)
remove-potion-effect	Remove a potion effect.	remove-potion-effect
run-command	Force a player to run a command.	run-command
send-action-bar	Sends a message to the player through the action bar.	send-action-bar
send-message	Send a message to the player.	send-message
set-attribute	Sets an attribute value (non-persistent).	set-attribute (duration)
set-default-attributes	Sets attributes back to their default value (non-persistent)	set-default-attributes
toggle-fly	Toggle fly for the player.	toggle-fly (true/false)
undisguise	Undisguise a player (requires LibsDisguises).	undisguise

Conditions

The third part of this tutorial is conditions. Conditions are pretty much self explanatory: they need to be passed in order for your trigger to work. Some triggers may also double-up as conditions, but may have different effects depending on how they're used. For example, the sneak trigger checks when you press the sneak button, but if you're using it as a condition, it returns as true any time you're sneaking. See the list below for a list of conditions:

Condition Name	Description	Usage
block-relative	Condition for when a block is relative to a player.	block-relative (See: BlockFace)
burn	Condition for when you're burning.	burn
day	Condition than checks when it is day.	day
disguised	Condition for when you're disguised	disguised (mob)
fly	Condition for when you're flying.	fly
health	Condition for health amount.	health <operator><health>
holding	Condition for when you're holding an item.	holding <item>
hunger	Condition for hunger amount.	hunger <operator><hunger>
in-biome	Condition for when you're in a certain biome.	in-biome
in-moonlight	Condition for when you're in the moonlight.	in-moonlight
in-region	Condition for when you're in a WorldGuard region.	in-region
in-sunlight	Condition for when you're in the sunlight.	in-sunlight
in-world	Condition for when you're in a specific world.	in-world
inside	Condition that checks when you're inside.	inside
moon-phase	Condition for moon phases.	moon-phase <phase (see Moon Phases)>
near-race	Condition for when you're near the specified race	near-race
night	Condition that checks when it's night.	night
outside	Condition that checks when you're outside.	outside
riding	Condition for when you're riding an entity.	riding
sneak	Condition for when you're sneaking.	sneak
time	Condition for when the time in the player's world is set to something.	time <operator><time>
ticks	Condition that checks if x amount of ticks have ran.	ticks

This may look like a lot to take in, but once you get started it should be a lot easier. Here are a few examples:

Basic trigger without any conditions that runs when you press sneak.

healonsneak:
    trigger: sneak
    delay: 10
    chance: 1
    run-passives:
    - give-health 20

Damages you when you're in water.

damageinwater:
    trigger: block-relative self water
    delay: 2
    chance: 1
    run-passives:
    - damage 1

Conditional trigger that gives you potion effects when damaging entities and when the given conditions have passed.

damageregen:
    trigger: damage-entity
    delay: 5
    chance: 100
    conditions:
    - night
    - moon-phase full
    - near-race Werewolf
    run-passives:
    - add-potion-effect regeneration 5 1

Trigger for giving race experience so players can level up.

damageforexp:
    trigger: damage-entity
    delay: 5
    chance: 20
    run-passives:
    - give-race-exp 5

And here is what it'd look like when put into a race:

race:
    name: Werewolf
    max-level: 30
    require-unlock: true
    gui:
        slot: 29
        icon:
            type: player_head
            owner: Werewolf
            display-name: "&cWerewolf &7| &aUnlocked"
            lore:
            - '&7At night, a dark curse falls upon'
            - '&7this race turning it into a vicious'
            - '&7werewolf!'
        icon-selected:
            type: player_head
            owner: Werewolf
            display-name: "&cWerewolf &7| &eSelected"
            lore:
            - '&7At night, a dark curse falls upon'
            - '&7this race turning it into a vicious'
            - '&7werewolf!'
            enchants:
            - unbreaking 1
            item-flags:
            - hide_enchants
        icon-locked:
            type: skeleton_skull
            display-name: "&c??? &7| &cLocked"
            lore:
            - '&7Defeat the Feral Lycan to'
            - '&7unlock this race.'
    levels:
        1: # The first level
            xp: 200 # How much experience you need to level up
            skillpoints: 1 # How many skillpoints you get for leveling up
        2: 
            xp: 250
            skillpoints: 1
        3: 
            xp: 275 # You don't need to define skillpoints either, but you MUST define how much xp it takes for you to level up.
        4: 
            xp: 300
            skillpoints: 1
        5:
            xp: 350
            skillpoints: 2
        # You can define as many levels as you want below
    attributes:
        generic-max-health: 25
        generic-armor: 5
        generic-attack-speed: 10
        max-mana: 250 # MagicSpells mana
    permissions:
    - essentials.sethome.multiple.werewolf
    - essentials.nick
    - essentials.tpa
    - ^essentials.tpahere # Add ^ before the permission to remove it
    - ^essentials.vanish 
    items:
        vampireknives:
            material: stone_sword
            display-name: "&4V&campire &4K&cnives"
            lore:
            - "&cRight-click to throw!"
        vampirefang: # You can define as many items as you want
            material: ghast_tear
            display-name: "&5V&dampire &4F&cang"
            enchantments:
            - sharpness 5
            item-flags:
            - HIDE_ENCHANTS
    triggers:
        walkongrass:
            trigger: block-relative down grass
            delay: 2
            run-passives:
            - add-potion-effect speed 2 2
        healonsneak:
            trigger: sneak
            delay: 10
            chance: 1
            run-passives:
            - give-health 20