A Gradle plugin for publishing Gradle build artifacts or other files directly to CurseForge. This project is community made and is not officially endorsed by CurseForge or Overwolf.
- Upload tasks directly to CurseForge using their official upload API.
- Auto-detect game version and mod loader based on build environment context clues.
- Task based publishing that allows for a wide range of scripting and configuration options.
- Upload to more than one CurseForge project.
This section will explain where to download this plugin, how it works, and all the available configuration properties.
This Gradle plugin is available from the official Gradle plugin repository. Both the Plugin DSL and legacy plugin applications are supported.
plugins {
id 'net.darkhax.curseforgegradle' version 'version_here'
}
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath group: 'gradle.plugin.net.darkhax.curseforgegradle', name: 'CurseForgeGradle', version: 'version_here'
}
}
This plugin uses a task based approach to uploading files. Projects define a new task in their build script that will publish various files when invoked. The following example demonstrates how a Java based project would upload their main JAR.
task publishCurseForge(type: net.darkhax.curseforgegradle.TaskPublishCurseForge) {
// This token is used to authenticate with CurseForge. It should be handled
// with the same level of care and security as your actual password. You
// should never share your token with an untrusted source or publish it
// publicly to GitHub or embed it within a project. The best practice is to
// store this token in an environment variable or a build secret.
apiToken = findProperty('curseforge_token')
// A project ID is required to tell CurseForge which project the uploaded
// file belongs to. This is public on your project page and is not private
// information.
projectId = findProperty('curseforge_project')
// Tells CurseForgeGradle to publish the output of the jar task. This will
// return a UploadArtifact object that can be used to further configure the
// file.
def mainFile = upload(projectId, jar)
mainFile.changelog = 'The changelog string for this file.'
}
Various examples for using CurseForgeGradle can be found here.
In some cases CurseForgeGradle will be able to automatically detect version tags from context clues in your build environment. This can be useful if you don't want to define them manually however the results may not be perfect. This can be disabled using disableVersionDetection()
within the body of your CurseForgeGradle task.
The following versions are detected when using CurseForgeGradle in a Minecraft project.
- When the
net.minecraftforge.gradle
plugin is applied in the same script theForge
tag will be applied. - When the
fabric-loom
plugin is applied in the same script theFabric
tag will be applied. - When the
MC_VERSION
,mc_version
, orminecraft_version
property is set its value will be added as a game version. - When a java toolchain is configured in the same script a corresponding java version tag will be added as a game version.
The following properties and methods are exposed for use within your script.
Name | Accepted Type | Description |
---|---|---|
apiToken | String|File|Closure | The API token used to authenticate with CurseForge. Setting this property is required to use this plugin. |
apiEndpoint | String|File|Closure | The API endpoint to upload the file to. This is an optional property and will default to the Minecraft API. |
debugMode | Boolean | Determines if publishing should actually happen or if the request should just be logged instead. This is an optional property and will default to false. |
upload(projectId, file) | String|Number, Object | Invoking this method will configure the task to upload a given file to a given project. The projectId can be a valid numeric String or any valid number. The file can be a file reference, an AbstractArchiveTask, or any other object Gradle can resolve as a file. This returns an UploadArtifact object which can be used to configure the file before publishing it. |
disableVersionDetection() | Invoking this method will disable automatic version detection for all files uploaded by this instance of the task. |
Name | Accepted Type | Description |
---|---|---|
changelog | String|File|Closure | The changelog for the file. This is optional. |
changelogType | String|File|Closure | The formatting type of the changelog. The default is plaintext but html and markdown are also accepted. |
displayName | String|File|Closure | An optional display name that will visually replace the file name. Using this method is often discouraged. |
releaseType | String|File|Closure | The type of release you are publishing. This accepts alpha, beta, and release. The default is alpha. |
addIncompatibility(slugs...) | String|File|Closure, ... | Marks the file as being incompatible with the specified project(s). |
addRequirement(slugs...) | String|File|Closure, ... | Marks the file as requiring a file from the specified project(s). |
addEmbedded(slugs...) | String|File|Closure, ... | Marks the file as containing an embedded implementation of another project(s). |
addTool(slugs...) | String|File|Closure, ... | Marks the file as having a tool relation with the specified project(s). |
addOptional(slugs...) | String|File|Closure, ... | Marks the file as having an optional dependency on the specified project(s). |
addModLoader(modloaders...) | String|File|Closure, ... | Adds one or multiple mod loader tags to the file. Known accepted values include Forge, Fabric, and Rift. |
addJavaVersion(versions...) | String|File|Closure, ... | Marks the file as being compatible with the given Java version(s). |
addGameVersion(versions...) | String|File|Closure, ... | Adds one or multiple game version to the file. This can only be used on parent files. |
addRelation(slug, type) | String|File|Closure, String|File|Closure | Adds a relationship between the file and another project. |
addRelations(type, slugs...) | String|File|Closure, String|File|Closure, ... | Adds a relationship between the file and multiple other project. Note: The parameters are in a different order than for addRelation |
withAdditionalFile(file) | Object | Creates a new UploadArtifact that will be uploaded as an additional/sub/child file. The provided object can be a file, ArchiveUploadTask, or any other value Gradle can resolve to a file. |
Project | Platform | Description |
---|---|---|
CurseGradle | Gradle | An alternative Gradle plugin for uploading files to CurseForge developed in Groovy. This has been the trusted go to plugin for many years and still works great. CurseForgeGradle was developed as a direct alternative because I prefer explicitly defining tasks and have other minor design preferences. |
Upload-To-CurseForge | GitHub Action | A GitHub Action that allows uploading files to CurseForge. This option is perfect for those who prefer GitHub actions. |