🚀Getting started

Since 1.0.0

This part of the guide (And everythig below this) is for plugin developers only as it shows how to implement features of MCUtils, not how to use them on a plugin that already exists. Please take into account that this guide assumes that you have a basic understanding about Java and the Spigot (Bukkit mostly) API, the guide does explain some very basic concepts some times, but don't expect this guide to tell you what a static method is.

Versions

Some features may be added in future versions, meaning that some of the features that you are currently seeing may not be present on all versions, that's why the page description exists, this one, for example, says "Since 1.0.0", meaning that the features on this page are present since the first version (Obviously), if any sub-element of a page was added on a different version as the one specified on the page description, it will be explicitly mentioned on it, so don't worry about that.

Adding MCUtils to your project

The best part about MCUtils is that your plugin doesn't need to depend on it, you can shade it into your project with maven, server owners don't need to install MCUtils, note that you may need to update / refresh your project for maven to actually download MCUtils so your IDE knows about it. If you want to skip the steps on how to do this, you can just copy an example pom.xml here.

Repository and dependency

The current repository example uses https://mcurepo.codersky.net/ as its url. This obviously depends on the codersky.net domain. If you want a more future proof but way longer version, you can use the github url: https://github.com/CoderskyNetwork/MCUtils/tree/mvn-repo/net/codersky/MCUtils. But keep in mind that if codersky.net stops working, chances are MCUtils is no longer maintained at that point, so you shouldn't really care about this.

<repository>
    <id>mcutils</id>
    <url>https://mcurepo.codersky.net/</url>
</repository>

<dependency>
    <groupId>net.codersky</groupId>
    <artifactId>MCUtils</artifactId>
    <version>1.0.0</version>
</dependency>

Shading and avoiding compatibility issues

MCUtils won't work with the previous maven setup, you need to shade it, right now, you can have issues with other plugins if they are also using MCUtils, this is because if you just shade MCUtils, other plugins will have the same package names as your plugin, for example net.codersky.mcutils.MCPlugin and Java doesn't like that (Obviously), luckily you can fix that with relocations.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.0</version> <!-- MAY NOT BE THE LATEST VERSION! -->
    <configuration>
        <minimizeJar>true</minimizeJar> <!-- Recommended, makes your jar smaller -->
        <relocations>
            <!-- Here starts the important stuff! -->
            <relocation>
                <pattern>net.codersky.mcutils</pattern>
                <!-- ## IMPORTANT: This is where MCUtils will be shaded! ## -->
                <shadedPattern>me.myname.myplugin.mcutils</shadedPattern>
                <!-- CHANGE "me.myname.myplugin" WITH YOUR PLUGIN PACKAGE IN lowercase -->
            </relocation>
            <!-- End of important stuff -->
        </relocations>
    </configuration>
    <!-- Executions and goals are also important, maven needs to know what to do -->
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Example pom.xml

Read it carefully, you need to replace some things, it's easy, don't worry, if it's your first time using maven or you don't understand what some things here do, we encourage you to do some research before copy-pasting this, it's important to understand what your code does.

If you want an actual real example, check out uSleep's code, the first plugin to use MCUtils.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>me.myname</groupId>
    <artifactId>AwesomePlugin</artifactId>

    <name>AwesomePlugin</name>
    <version>1.0.0</version>
    <description>This plugin is awesome!</description>

    <!-- Not really necessary, but it's cool to have UTF-8 -->
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <repositories>
        <!-- Spigot repository -->
        <repository>
            <id>spigot-repo</id>
            <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
        </repository>
        <!-- MCUtils repository -->
        <repository>
             <id>mcutils</id>
             <url>https://mcurepo.codersky.net/</url>
        </repository>
    </repositories>

    <dependencies>
        <!-- Spigot dependency -->
        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>1.20-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
        <!-- MCUtils dependency -->
        <dependency>
            <groupId>me.xdec0de</groupId>
            <artifactId>MCUtils</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>

    <build>
        <sourceDirectory>src/main/java</sourceDirectory>
        <plugins>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version> <!-- MAY NOT BE THE LATEST VERSION! -->
                <configuration>
                    <source>17</source> <!-- Java version of the plugin -->
                    <target>17</target> <!-- Java version of the plugin -->
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.0</version> <!-- MAY NOT BE THE LATEST VERSION! -->
                <configuration>
                    <minimizeJar>true</minimizeJar> <!-- Optional, makes your jar smaller -->
                    <relocations>
                        <relocation>
                            <pattern>net.codersky.mcutils</pattern>
                            <!-- ### IMPORTANT: This is where MCUtils will be shaded! ### -->
                            <shadedPattern>me.xdec0de.awesomeplugin.mcutils</shadedPattern>
                            <!-- CHANGE "me.xdec0de.awesomeplugin" WITH YOUR PLUGIN PACKAGE IN lowercase -->
                        </relocation>
                    </relocations>
                </configuration>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        <resources>
            <resource>
                <!-- Allows us to use maven variables on resource files -->
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
    </build>
</project>