Home

Mechanics Tutorial

Mechanics is a "simple" scripting language that lets you create custom actions (like sending a message or spawning a firework). Across our wikis, you often see a config key and then <Mechanics>, like this:

Weapon_Get_Mechanics: <Mechanics>

Whenever you see those <Mechanics>, that means you use all the features from this wiki!

Getting Started

Each line consists of 3 components:

Component	Description	Example	Optional
Mechanic	The action	Sound{sound=ENTITY_GENERIC_EXPLODE}
Targeter	Who the action affects	@Source{}
Conditions	Filter out who to affect	?Biome{biome=PLAINS}

Mechanic

The first and most crucial component is the Mechanic, which defines the action. Here is an example that sends a message to the player who caused the mechanic:

  - "Message{message=This is a Mechanic}"

Each mechanic has arguments. For the mechanic above, message is an argument. Every mechanic can use the following arguments:

Argument	Description	Default Value
repeatInterval	The number of ticks between repeating mechanics	$1$
repeatAmount	How many times to repeat the mechanic	$1$
delayBeforePlay	The number of ticks before the mechanic executes	$0$ (instant)
chance	The random chance the mechanic executes	$100\%$

  - "Message{message=This is a Mechanic, repeatInterval=20, repeatAmount=5, delay=200, chance=50%}"

This mechanic has a $50\%$ chance of executing. If it does execute, after $10$ seconds ($200\text{ ticks}=1\text{ second}$), 5 messages will be sent with $1$ second between each message.

Targeter

Targeters choose the "who" and the "where" the mechanic happens. For example, for a message, you should target a player. For some mechanics, like Message{}, you need to target an entity instead of a player.

Targeters always start with an @ character. A Targeter is not required, since it defaults to @Source{}. This means both of these are equivalent:

  - "Sound{sound=ENTITY_GENERIC_EXPLODE}"
  - "Sound{sound=ENTITY_GENERIC_EXPLODE} @Source{}"

Some targets use arguments. Every Targeter can use the following arguments:

Argument	Description	Default Value
offset	Offset the XYZ coordinates. You can use relative directions using ~. See Vector for more information.	$0\ 0\ 0$
eye	Target the entity's eye location instead of the location of its feet.	false

  - "Sound{sound=ENTITY_GENERIC_EXPLODE} @Source{eye=true, offset=~0 0 1}"

This mechanic will play the explosion sound 1 block in front of the eyes of the entity that caused the mechanics.

Conditions

Conditions let you filter out specific targets. You can use as many Conditions as you want. By default, no conditions are used. Conditions always start with a ? character.

Every Condition can use the inverted=true/false argument. When true the condition will be inverted, meaning the opposite must be true. For example:

"?Biome{biome=PLAINS}"  # only works in the plains biome
"?Biome{biome=PLAINS, inverted=true}"  # works in every biome EXCEPT plains