This is the source code for the Knokko's Custom Items minecraft plug-in:
- https://dev.bukkit.org/projects/custom-items-and-textures (BukkitDev)
- https://www.spigotmc.org/resources/knokkos-custom-items.88182/ (Spigot)
- https://www.mcbbs.net/forum.php?mod=viewthread&tid=1177493&extra=page%3D1%26filter%3Dsortid%26sortid%3D7%26searchoption%5B61%5D%5Bvalue%5D%3Dknokko%26searchoption%5B61%5D%5Btype%5D%3D (MCBBS) [Chinese] (This page is not made by me)
- https://polymart.org/resource/knokko-x27-s-custom-items.1190 (Polymart)
This plug-in makes it possible to add custom items with their own textures, without sacrificing existing minecraft items. (At least, if the (server) resourcepack is used.)
Normally, resourcepacks are used to change the textures of regular minecraft items to something that looks better. However, modern minecraft versions have resourcepack predicates, which make it possible to only assign custom textures to items under the right circumstances. One of these predicates allows the resourcepack to base its decision on whether the item stack to be shown is unbreakable or has lost durability. The resourcepacks generated by the Editor will assign different textures to item stacks that have lost durability, but are unbreakable. Such items clearly can't be obtained legitimately (players can't even obtain unbreakable items, let alone unbreakable items that lost durability). But, the plug-in can construct such items via the Bukkit API, which is how it will spawn such custom items in-game. The system described here is used to achieve the custom textures. The rest of the custom item features is not so special.
This repository is split into several modules:
The bit-helper module is a small library of mine that is used for compact binary (de)serialization. When I started this plug-in, I thought it was a good idea to use this, but I am starting to see its limitations. Nevertheless, it is very stable (has been used in production for more than 4 years without any failures) and its results are still quite good (although they could be improved).
This module is the source code for the Editor. This is a GUI application that users must use to configure the plug-in. The users must download it and run it on their computer. Using this GUI, they can configure their custom items (choose their textures, attack damage, display name, and lots of other stuff...).
This module is the (tiny) part of the plug-in that directly depends on CrazyEnchantments. Because CrazyEnchantments is compiled with Java 17 and
the plug-in
module needs to be compatible with Java 8, I can't just put this inside the plug-in
module. Some special built steps are used
to ensure that ce-event-handler
will be compiled using Java 17.
This module is a small gui library that I made a couple of years ago. When I started this custom items plug-in, I thought it was a good idea to use this library to write the Editor. After using it for a few years, I started seeing the limitations of this library: the scale of everything is based on the size of the window. This has the benefit that the editor will look the same to everyone, regardless of their screen resolution (try resizing your window to see what I mean), but has the drawback that this can cause distortion of text and images. Also, it lacks many interesting features that would have avoided the need of implementing all views myself. Switching to a different GUI library might be a good idea, but I am not so sure the amount of work is worth it.
This project has many kci-nms
modules. These modules take care of features that require a different implementation for each minecraft version.
For instance, these modules take care of NMS and some features that were added to the Bukkit API in later minecraft versions. The kci-nms
module itself defines the interface that is implemented by all the kci-nmsXX
modules. Each kci-nmsXX
module implements these interfaces
for minecraft 1.XX
. The modules kci-nms13plus
and kci-nms16plus
facilitate code reuse between kci-nms13
and later and kci-nms16
and later, respectively. Unfortunately, not every kci-nmsXX
module requires the same Java version, so this system is annoying. To work
around this problem, kci-nms17
and later are 'disabled' by default: they are commented out in build.gradle
and are not present in
settings.gradle
. So, unless you 'enable' them manually, development builds of this plug-in will not support minecraft 1.17 and later.
However, I did enable them in GitHub Actions, so these versions will be supported by release builds.
This module is the source code of the custom items plug-in itself. The plug-in essentially finds the binary configuration file generated by the Editor, deserializes it, and makes sure that everything configured in the Editor actually happens in-game.
This module contains the code that is used by both the Editor and the plug-in.
Before you can compile this project, you will need to get BuildTools from https://www.spigotmc.org/wiki/buildtools/ and then run the following commands using Java 8:
java -jar BuildTools.jar --rev 1.12.2 --compile CRAFTBUKKIT
java -jar BuildTools.jar --rev 1.13.2 --compile CRAFTBUKKIT
java -jar BuildTools.jar --rev 1.14.4 --compile CRAFTBUKKIT
java -jar BuildTools.jar --rev 1.15.2
java -jar BuildTools.jar --rev 1.16.5
Due to some juridical conflict, it is illegal to publish the entire craftbukkit jar, but it is legal to build it on your own computer using BuildTools... https://www.spigotmc.org/threads/why-exactly-does-the-buildtool-exist.341013/
You will probably want to use an IDE to work on this project. Regardless of your IDE, you should first clone, fork, or download this project as a
ZIP file. If you downloaded it as a ZIP file, you also need to extract it. Then, you should open it in an IDE. For Eclipse, use File -> Import ->
Gradle -> Existing Gradle Project -> Navigate file explorer to wherever you downloaded this project to and click on the root folder (normally
custom-items
). This might take a while the first time, so have some patience. For Intellij, use File -> Open... -> Navigate file explorer to
wherever you downloaded this project and click on the root folder (normally custom-items
). Then it should start doing all kinds of Gradle stuff
on the background, and you should wait for that to complete. It may happen that Intellij won't recognize imports yet after this step (this happens
on my computer). You can fix it by restarting Intellij.
Run ./gradlew test
to execute the unit tests.
In development, you can use ./gradlew shadowJar
to create a plug-in jar that should work on
minecraft 1.12 to minecraft 1.16. You can find it in plug-in/build/libs/plug-in-all.jar
.
Testing on later minecraft versions can be done by manually modifying build.gradle
and
settings.gradle
. In particular, you need to uncomment the kci-nmsXX
project for the
corresponding minecraft version in build.gradle
and add it to settings.gradle
.
The Editor can be found in editor/build/libs/editor-all.jar
, which you can double-click
to run it. However, this is not very interesting since you can also just run the Editor via
your IDE.
For production, you should simply push all your changes to GitHub, which will cause a
GitHub Actions workflow to produce everything. Unlike the development build, this will
work on all minecraft versions supported by this plug-in. Everything will be put in a
releases.zip
artifact for the commit, which contains the following files:
CustomItems.jar
: the jar file that should be put in theplugins
folder of the serverEditor.jar
the 'raw' Editor: people with a Java installation can double-click it to run the Editor.editor-linux.zip
: Linux users without Java installation can download this, extract the contents, and double-clickeditor
to run the Editoreditor-macosx.zip
: Mac users without Java installation should be able to run the Editor using this file, but I'm not exactly sure how since I don't have a Maceditor-windows.zip
: Windows users without Java installation can download this, extract the contents, and double-clickeditor.exe
to run the Editor
The primary advantage of the 'raw' Editor.jar
over the native editors is that it is significantly smaller since
it doesn't need to bundle a complete JRE.
If you don't like build systems, you can simply download CustomItems.jar from Spigot or BukkitDev and add it to your classpath.
Add the Jitpack maven repository:
repositories {
// Your current repositories...
maven { url 'https://jitpack.io' }
}
And add the modules you want to your dependencies:
dependencies {
// Your current dependencies...
// You probably want shared-code and plug-in
compileOnly 'com.github.knokko.custom-items-gradle:shared-code:master-SNAPSHOT'
compileOnly 'com.github.knokko.custom-items-gradle:plug-in:master-SNAPSHOT'
// You may also want to have e.g. the Editor
compileOnly 'com.github.knokko.custom-items-gradle:editor:master-SNAPSHOT'
}
Add the Jitpack maven repository:
<repositories>
# Your current repositories...
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
And add the modules you want to your dependencies:
# Your current dependencies...
<dependency>
<groupId>com.github.knokko.custom-items-gradle</groupId>
<artifactId>shared-code</artifactId>
<version>master-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>com.github.knokko.custom-items-gradle</groupId>
<artifactId>plug-in</artifactId>
<version>master-SNAPSHOT</version>
</dependency>