Project Setup

The Bukkit community as a whole commonly uses IntelliJ IDEA as the editor of choice for Java development. As such, the tutorials on this page will assume you are using IntelliJ IDEA. Although, the tutorial below should work with any IDE albeit slight changes.

Creating Your Project

Open IntelliJ IDEA and select the option to create a new project. You will get the option to select the type of project you want to create - select New Project > Java.

Select Gradle - Kotlin DSL.
Ensure your JDK is 21. The JDK brand doesn’t matter, but the version does!

Give your project a name and click + Advanced Settings.

Select Gradle distribution Wrapper.
Set your group id to me.<your_username>.exampleplugin.
Set your artifact id to ExamplePlugin.

Finally, click create. You will land into the build.gradle.kts file where you can add your dependencies.

Project Structure

A file tree overview of what folders and files are necessary for a Canvas plugin project.

DirectoryExamplePlugin/
- Directorybuild/
  - Directorylibs/
    ExamplePlugin-1.0.jar
- Directorygradle/
  - …
- Directorysrc/
  - Directorymain/
    Directoryjava/
    Directoryio.canvasmc.exampleplugin
    ExamplePlugin.java
    Directoryresources/
    plugin.yml
- build.gradle.kts
- settings.gradle.kts
- gradlew
- gradlew.bat

Your Plugin’s Main Class

This will be Canvas’ entry point to your plugin and the only class that will extend JavaPlugin. In this class, you should register your commands, listeners, and any other code that your plugin needs immediately after server startup.

package io.canvasmc.exampleplugin;

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.minimessage.MiniMessage;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;

// An example of what a simple plugin's main class could look like
public class ExamplePlugin extends JavaPlugin implements Listener {
    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        // Change the message shown to everyone online when someone joins
        Player player = event.getPlayer();
        Component newMessage = MiniMessage.minimessage().deserialize("<red>Welcome to Canvas, " + player.getName() + "!");
        event.joinMessage(newMessage);
    }
}

The plugin.yml

The plugin.yml is the descriptor file for your plugin. It’s necessary for Canvas to get important information about your plugin at runtime. In this example, we’ll be using the simple plugin.yml, but Canvas also supports paper-plugin.yml files too!

name: ExamplePlugin
version: '$version' # Controlled by your build.gradle.kts
main: io.canvasmc.exampleplugin.ExamplePlugin
description: An example plugin
author: CanvasMC
website: https://canvasmc.io
api-version: '1.21.11'
canvas-supported: true # If your plugin is compatible with standard Folia servers, use `folia-supported: true` instead!

Your Build File

The build.gradle.kts will be your build script for your plugin. It is the center of the project and controls how your plugin will be built. In this tutorial we’ll just be showing a basic build script that also automatically fills in the version key in your plugin.yml

plugins {
    java
}

group = "io.canvasmc.exampleplugin"
version = "1.0"

repositories {
    mavenCentral()
    maven("https://maven.canvasmc.io/snapshots")
}

dependencies {
    compileOnly("io.canvasmc.canvas:canvas-api:1.21.11-R0.1-SNAPSHOT")
}

tasks.processResources {
    // Replaces `$version` in your `plugin.yml` with the `version` field in this file
    val props = mapOf("version" to project.version)
    filesMatching("plugin.yml") {
      expand(props)
    }
    // Ensures special characters don't get malformed when compiling
    filteringCharset = Charsets.UTF_8.name()
}

tasks.withType<JavaCompile>().configureEach {
    // Ensures special characters don't get malformed when compiling
    options.encoding = Charsets.UTF_8.name()
}

java {
    // Enforces JDK 21 (required for Minecraft 1.21.11)
    toolchain.languageVersion = JavaLanguageVersion.of(21)
}

Project Settings

Your settings.gradle.kts controls your project’s name and a few other miscellaneous things.

// Controls the name of your project
rootProject.name = "ExamplePlugin"

Building

Assuming you’ve setup your project correctly, you should be able to build it and get a runnable jar file! This jar should be placed in the ~/plugins directory of your Canvas server.

./gradlew build

gradlew build