Skip to main content

Your first bundle

This lesson gets a working bundle into the game. By the end you will have cloned a bundle, edited its identity, run the game, and loaded your own bundle in it.

You need Java 25 and the IntelliJ IDEA IDE. If you do not have them, install a Java 25 JDK and IntelliJ IDEA (Community works) before you start.

What a bundle is​

A bundle is a folder of Groovy scripts, textures, and data. The game reads it at runtime, so you change content without compiling Java. This tutorial uses a copy of the Minimal Bundle found in the FoundryEngine repository.

Launch the Game one time​

The game must be launched once to generate all necessary files.

Open the Minecraft Folder in IntelliJ​

Open IntelliJ IDEA, then open the minecraft folder as a project. IntelliJ imports it as a Gradle project.

The first Gradle sync downloads NeoForge and Minecraft and decompiles them. This can take up to an hour on a slow machine. Let it finish. When it is done, the project compiles and IntelliJ shows the Gradle tool window.

Copy the Minimal Bundle​

Copy the minimal bundle from the FoundryEngine repository, specifically under the "ExampleBundles" folder. Place it in FoundryEngine/bundles/ inside your .minecraft directory.

Set the identity of the bundle​

A bundle knows who it is through one file.

Open minimal.bundles.toml and set your own values:

[[bundles]]
bundleId = "mybundle"
version = "1.0.0"
displayName = "My Bundle"
displayURL = "https://example.com/my-bundle"
authors = "Your Name"
description = "What this bundle does."
dependencies = [
    "mod:neoforge@26.1.0.1-beta"
]

Add an entrypoint​

A bundle needs at least one entrypoint. Create a Groovy class that implements BundleEntrypoint under scripts.

scripts/common/mybundle/MyBundle.groovy is a good place to start:

package common.mybundle

import de.luckymcdev.foundryengine.script.common.BundleEntrypoint

class MyBundle implements BundleEntrypoint {

    @Override
    void onLoad() {
        println "My bundle loaded!"
    }

    @Override
    void onUnload() {
        println "My bundle unloaded!"
    }
}

onLoad runs when the bundle loads. onUnload runs when it reloads or is removed.

Run the game​

Run the game from your launcher. The engine extracts Gradle templates to your game directory on first launch, so you can open the minecraft folder as a Gradle project in IntelliJ after that.

Check the outcome​

You should now see the message "My bundle loaded!" in the console.

Next, give the bundle content. Continue to Your first item.

Troubleshooting​

  • The first sync is slow. NeoForge is large. Let it finish once; later syncs are faster.