Skip to content

Compiling

Jump to bottom
aokod edited this page Dec 27, 2025 · 3 revisions

This guide will walk a novice Minecraft player through the process of compiling the TotalFreedomMod plugin from its source code.

In this guide, "compiling a program" refers to the process of translating the source code and converting it to bytecode to be read by the server runtime. For a more detailed explanation, refer to the Oracle Java article: Compiling; Running a Simple Program

Why do I need to compile?

Unlike most Minecraft plugins where you can just downloaded a .jar binary file, TotalFreedomMod's license requires that it be distributed as source code only.

Redistributions of This Software must solely occur in Source form. Redistribution in Object form is prohibited without prior written permission from the Licensor.
§ 2.1 of the TotalFreedom General License

This means that you need to compile the source code into a working plugin yourself. For those of you who have never compiled a plugin before: this may seem like a difficult task, but it is actually very straightforward if you pay attention to the nature of the task at hand.

Specifications

Component Details
Java version 21 (required)
Build system Gradle 8.10.2 (not required, standard)
Target platform Paper (see README.md for version details)
Plugin version 6.x (see tfm.build.version)

Getting started

TotalFreedomMod requires Java 21 to compile and run. If you are actively playing the latest version of Minecraft, chances are that you already have Java JDK 21 installed on your computer. On the other hand, if you are still unsure, refer to the Oracle Java Version Manual.

In addition to Java, you will also need an internet connection.

Download Java JDK 21

There are numerous ways to download (or build) and run Java.

The OpenJDK is the open source reference implementation of the Java SE Specification, but it is only the source code. Binary distributions are provided by different vendors for a number of supported platforms. These distributions differ in licenses, commercial support, supported platforms, and update frequency.
Distributions, Which Version of JDK Should I Use? by Jochen Christ

Here are some of the most common distributions:

  1. Adoptium Temurin 21
  2. Oracle JDK 21
  3. Amazon Corretto 21

Installation

  • Windows: Download the .msi (or .exe) installer and follow the prompts.
  • macOS: Download the .pkg installer or use Homebrew: brew install openjdk@21
  • Linux: Use your package manager (e.g. sudo apt install openjdk-21-jdk)

To verify your installation, open a terminal (or command prompt) and type java -version, which should output version 21.

Obtaining the source code

Naturally, the TotalFreedomMod source code should be obtained from its GitHub repository (which is here). We recommend that you use Git in order to maintain headache-free version control.

git clone https://github.com/tfreedomorg/TotalFreedomMod.git
cd TotalFreedomMod

On the other hand, you may find it easier to download the source code in archive (ZIP) form.

Compiling from source

Now that you have the source code, you may use it in order to compile the plugin. After opening a terminal/command prompt in the source folder, you should be able to use the Gradle Wrapper to initialize the build tool.

./gradlew build

In the Windows command prompt, instead use: gradlew.bat build

The first time that you run this command, it will download the Gradle build tool and all required libraries. This may take a few minutes depending on your Internet speed. After downloading the build tool, the Wrapper will proceed to build the plugin.

Once the build completes successfully, you'll see BUILD SUCCESSFUL. If your build doesn't complete successfully, consider troubleshooting online (Gradle is a widely-used tool) or, if you believe the build error to be specific to TotalFreedomMod, then don't hesitate to open an issue.

Common build errors

  • java: command not found or 'java' is not recognized — Java isn't properly installed or isn't located in your system PATH. Reinstall Java and make sure to check "Add to PATH" during installation.
  • Could not find or load main class org.gradle.wrapper.GradleWrapperMain — The Gradle wrapper files are missing; re-download the source code.
  • Permission denied — Make sure the Gradle wrapper is executable with chmod +x gradlew (or "Run as Administrator" on Windows).

Using your build

After a successful build, your compiled plugin .jar binary file should be located at:

TotalFreedomMod/build/libs/TotalFreedomMod-1.2.3.jar (your version here)

From this point onwards, you may copy the newly-compiled .jar binary file to your server's plugins/ directory, restart the server, and you should hopefully find success thereafter in running the plugin on your server.

Clone this wiki locally