Build addons

Addon development

Create, package, and load an addon using Foundry's actual addon contract.

On this page

Addon structure

An addon is a JAR with a foundry.yml file at its root and a main class that implements FoundryAddon. The descriptor names the addon class, which Foundry constructs with a no-argument constructor.

yaml
id: example-addon
version: 1.0.0
main: me.example.ExampleAddon
FieldMeaning
idRequired. Must match the addon's id and contain only lowercase letters, digits, underscores, or hyphens.
versionDescriptor metadata. The loaded version shown in logs comes from the addon's version property.
mainRequired fully qualified class name. The class must implement FoundryAddon and expose a no-argument constructor.

Implement the addon

Foundry calls onEnable(api) after constructing the addon. Use the supplied FoundryAPi instance to register abilities and access the server plugin. The repository's example addon compiles against the root Gradle project using a compileOnly project dependency.

kotlin
class ExampleAddon : FoundryAddon {
    override val id = "example-addon"
    override val version = "1.0.0"

    override fun onEnable(api: FoundryAPi) {
        api.abilities.register(GreetingAbility())
    }

    override fun onDisable() {
        // Release addon-owned resources here.
    }
}
kotlin
dependencies {
    compileOnly(project(":"))
}

Package and load

  • Build the addon JAR with its foundry.yml at the archive root.
  • Copy the JAR directly into plugins/Foundry/packs.
  • Restart the Paper server. Foundry scans files whose extension is .jar (case-insensitive) when its onEnable() runs.
bash
./gradlew :FoundryExampleAddon:build