EN_UsingTheAPI - MMonkeyKiller/CustomBlocks GitHub Wiki

Using the API

This post is only for developers

Using the API, you have more control of every customblock, from their asignation, function, or interaction

Implementing CustomBlocks as a maven dependency

Add the following lines in your pom.xml at the correct location

<dependency>
	<groupId>com.github.MMonkeyKiller</groupId>
    <artifactId>CustomBlocks</artifactId>
    <version>VERSION</version>
	<scope>provided</scope>
</dependency>

Remember, you need to specify the version!

...
<repository>
    <id>jitpack.io</id>
	<url>https://jitpack.io</url>
</repository>
...

Now add CustomBlocks as a plugin.yml dependency

depend: [CustomBlocks]

Using the API

Now included as a dependency, we need to use it correctly in the project

First, we need to overwrite the custom block registry in ram, and add your owns (we are ignoring the custom block list in config.yml)

public class myPlugin extends JavaPlugin {

	@Override
	public void onEnable() {
		System.out.println("Example plugin enabled!");
		registerCBlocks();
	}

	public void registerCBlocks() {
		CustomBlocksAPI api = new CustomBlocksAPI();
        api.clearRegistry();
	}
}

Keep in mind that by specifying it as a dependency in the plugin.yml, we make sure that our plugin loads after CustomBlocks

Ok! With this we are clearing the list of custom blocks generated by the plugin's config.yml, but there is still a problem.

If the /cb reload is used on the server, the configuration will reload, so we need to clean the registry again on every reload

For this we will use an api event, called CBLoadEvent. To use it we will register it like any bukkit event

	// don't forget this must be in a class implementing Listener

	@EventHandler
	private void onCBLoad(CBLoadEvent event) {
		System.out.println("CustomBlocks reload detected! Registering blocks...");
		registerCBlocks();
	}

	@EventHandler
	private void onPluginEnable(PluginEnableEvent event) {
		if (event.getPlugin().getName().equalsIgnoreCase("CustomBlocks"))
			registerCBlocks();
		// With this event we reload the blocks if the plugin is reloaded by external conditions (ex. Plugman)
	}

Now, finally, we will create our custom block, for this we create a child class of CustomBlock

public class myEpicBlock extends CustomBlock {
	public myEpicBlock() throws Exception {
        super("myplugin:my_epic_block", 1000, Instrument.BANJO, 1, false);
		//	id, modelData, instrument, pitch, powered, [item material]
    }
}

We will also create a directional block (currently only available using the API). We need to create a child class of DirectionalCustomBlock

The directional blocks are still being designed, maybe the way to create one will change in the future

public class myDirectionalBlock extends DirectionalCustomBlock {
	public myDirectionalBlock() throws Exception {
		// On directional blocks, the instrument, the pitch, and the powered state will be overwritten by the directional variants, you can put any value on these fields
		super("myplugin:my_directional_block", 1001, Instrument.BANJO, 2, false, new HashMap<BlockFace CustomBlockData>() {{
            put(BlockFace.NORTH, new CustomBlockData(Instrument.BANJO, 2, false));
            put(BlockFace.SOUTH, new CustomBlockData(Instrument.BANJO, 3, false));
            put(BlockFace.EAST,  new CustomBlockData(Instrument.BANJO, 4, false));
            put(BlockFace.WEST,  new CustomBlockData(Instrument.BANJO, 5, false));
            put(BlockFace.UP,    new CustomBlockData(Instrument.BANJO, 6, false));
            put(BlockFace.DOWN,  new CustomBlockData(Instrument.BANJO, 7, false));
        }});
		//	id, modelData, instrument, pitch, powered, [item material]
	}
}

The way to create them is a bit different than a simple block. At the time you call the builder, you will need to specify the instrument, pitch, and the powered status. This doesn't matter as it will be overwritten by the orientation variation.

There is a new required parameter on the constructor, a HashMap<BlockFace, CustomBlockData>, which should have a CustomBlockData assigned for NORTH, SOUTH, EAST, WEST, UP, DOWN.

After creating a class for each block, we will add them to the registry

public void registerCBlocks() {
	CustomBlocksAPI api = new CustomBlocksAPI();
    api.clearRegistry();
	try {
		api.register(
			new myEpicBlock(),
			new myDirectionalBlock()
		);
	} catch (Exception ex) {
		e.printStackTrace();
	}
}

We can also add a function to it by right-clicking it, for example:

public class myEpicBlock extends CustomBlock implements Interactable {
	public myEpicBlock() throws Exception {
        super("myplugin:my_epic_block", 1000, Instrument.BANJO, 1, false);
		//	id, modelData, instrument, pitch, powered, [item material]
    }

	@Override
    public void onInteract(@NotNull Player player, @NotNull Block block) {
        player.sendMessage("Hey!");
    }
}

It should be noted that it is not necessary to do the clearRegistry(), i did this because i like to register each block at code level, so i have a better control of its operation

Congratulations! You are making basic use of the API! In the future, i will enrich this page with more advanced usages of the API

⚠️ **GitHub.com Fallback** ⚠️