Manually editing YMLs
THIS IS FOR ADVANCED USERS ONLY
If you're new to CustomEvents, you should be using the in-game GUI to create your events. Open it with /ce create. That's it!
Remember: INDENTATION IS VERY IMPORTANT! If you run into any issues with YAML formatting, try using yamllint.com.
Certain events, actions, and conditions are only available on the newest versions of Minecraft. If you're using an older version of Minecraft, google "Minecraft <version> javadocs" to get a list of all the available events/actions/conditions instead of using the links here. For example, you should use https://helpch.at/docs/1.8.4/ to get the list of available events on 1.8.4.
In this example, we'll make something that replaces all dirt blocks that the player places with grass blocks
CustomEvents YML files are formatted like the below example. It's recommended that you first make a very simple trigger with the /ce create GUI to see how things should be formatted
handlers:
TriggerTypeOne:
actions:
-
action: myAction
parameterOne: valueOne
parameterTwo:
- list
- of
- values
-
if:
conditionOne: conditionValueOne
conditionTwo: conditionValueTwo
action: anotherAction
anotherParameter: anotherValue
TriggerTypeTwo: #...
TriggerTypeThree: #...
You can find a full list of the available trigger types on https://hub.spigotmc.org/javadocs/spigot/index.html under the "org.bukkit.event" packages, like "org.bukkit.event.player". For example, if you click "org.bukkit.event.block", you'll see that BlockPlaceEvent is an option for a trigger. You can leave the "Event" part off of any of these triggers, and just use BlockPlace instead.
Bookmark this page, because you'll be using it a lot!
Under your trigger name, add actions. Under actions, add a list of actions, like so:
handlers:
BlockPlace:
actions:
-
action: #...
# ...
-
action: #...
-
action: #...
Now, let's write an action.
First, let's find out what we can run the actions on. On the javadocs website we just visited, click on BlockPlaceEvent to see a full list of all the available objects we can run the action on: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/block/BlockPlaceEvent.html. You'll be able to see everything under the Method Summary header — we can use anything that starts with get, just make sure to remove the get prefix when you write down the name of the object.
For example, for BlockPlace, we have getBlockAgainst, getBlockPlaced, getBlockReplacedState, getHand, getItemInHand, and getPlayer. We can also use getBlock and getEventName (these are "inherited" methods. This means absolutely nothing to CustomEvents, but if you're curious what it means, try looking up "Java method inheritance"). We also have getHandlers and getHandlerList, but these are advanced methods you'll probably never use (I've never even used them when I coded any of my plugins).
If we wanted to do something with the block that we placed against, we would look at the getBlockAgainst method. Remember, we remove the "get", so we would call this blockAgainst. Similarly, if we wanted to do something with the player, we would call this player. If we wanted to do something on the item in the player's hand, we would call this itemInHand... you get the idea
We want to do something with the block that's placed. So, let's look at the getBlockPlaced — we remove the "get" to get the name of the object, which is blockPlaced.
So far, our action looks like this
action: blockPlaced ??? # We'll replace ??? with the actual action that we run on the placed block
Now, let's find a list of all of the actions we can run on this object. Click on the method name getBlockPlaced, and you'll be brought to a definition for the method. Click on the type of the object, which comes right before the method name. For example, the definition of getBlockPlaced looks something like this:
@NotNull
public Block getBlockPlaced()
This means that blockPlaced is some sort of Block. Click on Block, and you'll be brought to a list of all of the things you can do with blocks: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/block/Block.html
Scroll down to the Method Summary section. Here, you'll see a whole bunch of actions that you can run on the block. We probably don't want to use anything that starts with get. Instead, most of what you'll do is something that starts with set, although it might start with something else.
We want to set the type of the block, so scroll until you find something that might help us do that. Stop reading if you want to try to find it yourself. Otherwise, keep reading and I'll put the method name in the next paragraph.
A-ha! It's called setType! This is the name of the action that we want to run on blockPlaced. An action is formatted like this
action: <what we're running the action on> <the name of the action>
So, if we want to run the setType action on blockPlaced, our action should look like this
action: block setType
But, we're not done yet! We still need to tell CustomEvents what we should set the type of the block to. Click on the setType method, and you'll be brought to the method definition: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/block/Block.html#setType(org.bukkit.Material)
Here, we can see that the setType method accepts one argument: type. What are our different options for type? The word that comes right before type tells you what type is
void setType(@NotNull Material type)
So, we can see that type is a Material. Click on Material to see the different options of materials: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
Scroll down to the Enum Constants Summary section, and find the option that you want. We want to set blocks to diamond blocks, so, we'll use DIAMOND_BLOCK
Make sure to read this important dropdown about types
There's a lot of different types. For the most part, they're pretty straightforward. Here's what some common types mean:
String is just a string of characters like "Hello, World"
Byte, byte, Short, short, Integer, int, Long, and long are all different types of integer numbers (no decimals). Google "Java number storage sizes" to see how big of a number each one can be.
Float, float, Double, and double are all different types of decimal numbers.
Boolean and boolean could be either true or false
Object could be anything — you should probably just provide a "string".
For anything else, click the type. If it says Enum somewhere on the page, you can use any of the options provided under the Enum Constants Summary header. For example Material says Enum Material at the top, so you could use something like "GRASS_BLOCK" or "DIAMOND_PICKAXE".
If it does not say Enum at the top (for example, Chunk does not), you'll have to go through some more advanced routes to get the object, which is out of scope for this dropdown. Ask on the Discord!
Anything that looks like Something[], or like List<Something>, Set<Something>, Collection<Something>, etc, you should use a list of Something as the value. For example, if it's String[] or List<String>, you should do something like this
- "First Value"
- "Second Value"
- "Third Value"Anything that looks like Map<A, B> or HashMap<A, B>, etc, you should use a map of A to B as the value. For example, if it's Map<String, String>, you should do
"First Key": "First Value"
"Second Key": "Second Value"
"Third Key": "Third Value"Rarely, things will even be mix-and-matched. For example
List<Map<String, List<Integer>>
-
key:
- 0
- 1
- 2
key2:
- 1827
- 8917
- 118
-
anotherKey:
- 1
- 9
-
lastKey:
- 0
The portion of the action that sets the block is finished!
action: blockPlaced setType
type: "DIAMOND_BLOCK"
If you want, you can also use ItemBridge keys for the type to integrate with other plugins like CustomItems "cui:myCustomItemsBlock"
Lastly, let's add the condition to only set the block to diamond when the user places dirt
if:
blockPlaced type: "DIRT"
action: blockPlaced setType
type: "DIAMOND_BLOCK"
Putting it all together
handlers:
BlockPlaced:
actions:
-
if:
blockPlaced type: "DIRT"
action: blockPlaced setType
type: "DIAMOND_BLOCK"
