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
  IMPORTANT info about types


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"