Configuration
Add a hytalePublisher block to your build.gradle file.
hytalePublisher {
// Optional global release metadata
version = project.version
releaseType = "release" // "release" | "beta" | "alpha"
// Defaults to project.hytale_version if present.
// Accepts dynamic selectors like "0.+" — see Game Version below.
// gameVersion = project.hytale_version
changelogFile = "changelog.md" // Relative to the root project directory
// Created automatically if missing
// Existing files are matched case-insensitively, e.g. CHANGELOG.md
modtale {
enabled = true
projectId = "your-modtale-project-id"
// Hytale patchline used to resolve dynamic gameVersion selectors.
// Has no effect when gameVersion is set to a concrete version.
// patchline = "release" // or "pre-release"
// Optional credential key overrides
// apiKeyProp = "modTaleKey"
// apiKeyEnv = "MODTALE_KEY"
// When true, re-uploading the same versionNumber for overlapping gameVersions
// replaces the existing version on those targets instead of failing.
// Non-overlapping targets on the old entry are not affected.
// replaceExisting = false
// Dependencies: required(modId, minVersion) / optional(modId, minVersion)
required "5e9bbea3-0d7f-4365-93df-5e7acfadf0e7", "1.0.4"
optional "2ebf130e-2189-4e90-9323-803a374d05ce", "1.5.2"
}
curseforge {
enabled = true
projectId = "123456" // Your CurseForge numeric project ID
// Optional game version ID override, only for advanced users
// gameVersionIds = [14284]
// Dependencies: required / optional / embeddedLibrary / incompatible / tool
required "levelingcore"
optional "dynamictooltipslib"
embeddedLibrary "bundled-helper"
incompatible "broken-addon"
tool "dev-tooling-helper"
}
modifold {
enabled = true
projectId = "your-modifold-project-slug"
// Must exactly match the game version names shown by Hytale / Modifold.
// Can contain one or many supported versions.
gameVersions = [
"0.5.0-pre.9.1",
"0.5.0-pre.9",
"0.5.0-pre.8",
"0.5.0-pre.7"
]
// Must be a list; automatically JSON-encoded for the API.
loaders = ["Vanilla"]
// Dependencies: required / optional / incompatible / embedded
// Second argument is an optional Modifold version_id; omit for "any version"
required "mermaids", "oCK3bg"
optional "prettier-than-before"
incompatible "broken-mod"
embedded "bundled-helper", "abc123"
}
thunderstore {
enabled = true
// Required: the Thunderstore team (namespace) you upload under
namespace = "YourTeam"
// Optional: defaults to project.name with spaces -> underscores
// packageName = "Your_Mod_Name"
// Optional
// websiteUrl = "link_to_your_sources"
// Optional: defaults to project.description, max 250 chars
// description = "A short description of the mod."
// Defaults to "hytale" — the Thunderstore community slug for Hytale
// community = "hytale"
// Tag the package per the Hytale community categories. Browse at
// https://thunderstore.io/api/experimental/community/hytale/category/
categories = ["plugins", "mods", "release"]
// Required by Thunderstore TOS if applicable
// hasNsfwContent = false
// Dependencies in Thunderstore "Namespace-PackageName-Version" format
dependency "Hytale", "HytaleAPI", "8.8.1"
dependency "Hytale-HytaleAPI-8.8.1" // alternative single-string form
// --- Content bundling -------------------------------------------------
// Each helper places a file/folder into the Thunderstore-required folder
// structure inside the package zip:
//
// plugin(path) -> mods/<name>.jar
// earlyPlugin(path) -> earlyplugins/<name>.jar
// assetPack(path) -> mods/<name>.zip
// world(path) -> worlds/<dir>
// universe(path) -> universes/<dir>
// save(path) -> saves/<dir>
//
// If you don't call any of these, the plugin's built jar is auto-placed
// into mods/ — matching the Hytale Modding Thunderstore plugin guide.
//
// plugin "build/libs/MyMod-${project.version}.jar"
// world "src/main/resources/worlds/my-cool-world"
}
github {
enabled = true
// Optional: "owner/repo". Auto-detected from the "origin" git remote if omitted.
// repository = "AzureDoom/Ovomorphosis"
// Optional credential key overrides
// apiKeyProp = "githubToken"
// apiKeyEnv = "GITHUB_TOKEN"
// Tag applied to the release commit, e.g. "v1.0.0". The tag is created
// automatically by GitHub as part of creating the release — no separate
// git tag/push step is needed.
// tagPrefix = "v"
// Optional: commit or branch the tag points at. Defaults to the current HEAD.
// targetCommitish = "main"
// Optional: release title. Defaults to "<projectName> <projectVersion>".
// releaseName = ""
// draft = false
// prerelease = false
// When true (default), releaseType values other than "release" (e.g. "beta",
// "alpha") automatically mark the GitHub release as a prerelease.
// autoPrerelease = true
// Let GitHub append its auto-generated notes after the changelog body.
// generateReleaseNotes = false
// Mirrors GitHub's make_latest release field: "true" | "false" | "legacy"
// makeLatest = "true"
// Optional: opens a linked discussion for the release under this category.
// discussionCategoryName = ""
// Attach the built jar, sources jar, and javadoc jar. Sources/javadoc are
// skipped automatically (with a warning) if those tasks aren't present.
// includeJar = true
// includeSourcesJar = true
// includeJavadocJar = true
// Only relevant if your sourcesJar/javadocJar tasks use non-standard names
// sourcesJarTaskName = "sourcesJar"
// javadocJarTaskName = "javadocJar"
// Attach any additional files to the release
// asset "build/libs/extra-debug-symbols.zip"
}
maven {
enabled = true
// Required: where release versions get uploaded
url = "https://maven.azuredoom.com/mods"
// Optional: used instead of `url` when the resolved version ends with "-SNAPSHOT"
// snapshotUrl = "https://maven.azuredoom.com/mods-snapshots"
// Optional: allow plain http:// repository URLs (disabled by default for safety)
// allowInsecureProtocol = false
// Optional credential key overrides
// usernameProp = "mavenUsername"
// usernameEnv = "MAVEN_USERNAME"
// passwordProp = "mavenPassword"
// passwordEnv = "MAVEN_PASSWORD"
// Optional: defaults to project.group / project.name / hytalePublisher.version
// groupId = "com.azuredoom"
// artifactId = "levelingcore"
// version = project.version
// Optional: names for the Gradle publication and repository. Only relevant
// if you need to reference them elsewhere in your build.
// publicationName = "maven"
// repositoryName = "custom"
// Attach the built jar, sources jar, and javadoc jar. Sources/javadoc are
// skipped automatically (with a warning) if those tasks aren't present.
// includeJar = true
// includeSourcesJar = true
// includeJavadocJar = true
// Only relevant if your jar/sourcesJar/javadocJar tasks use non-standard names
// jarTaskName = "jar"
// sourcesJarTaskName = "sourcesJar"
// javadocJarTaskName = "javadocJar"
// Attach any additional files to the publication
// artifact "build/libs/extra-debug-symbols.zip"
// Optional POM metadata
// pomName = "LevelingCore"
// pomDescription = "Rendering and animation library for Hytale mods"
// pomUrl = "https://github.com/AzureDoom/LevelingCore"
// Escape hatch for anything not covered above — delegates to Gradle's
// MavenPom directly (licenses, developers, SCM info, etc.)
// pom { pom ->
// pom.licenses {
// license {
// name = "MIT License"
// url = "https://opensource.org/licenses/MIT"
// }
// }
// }
}
}By default, HytalePublisher uses the hytale_version project property if present.
You can define this in gradle.properties:
hytale_version=your-game-versionIf hytale_version is not set, some platforms (such as Modtale) may reject uploads due to invalid game version values.
This value is used for platforms like Modtale that require a specific version string.
You typically do not need to set gameVersion manually unless you want to override this behavior.
gameVersion accepts Gradle-style dynamic version selectors so you can track the latest Hytale build without updating gradle.properties for every server release:
hytalePublisher {
gameVersion = "2026.+" // latest 2026.x build on the configured patchline
modtale {
enabled = true
projectId = "your-modtale-project-id"
patchline = "release" // or "pre-release"
}
}Supported selectors:
-
2026.+— latest version starting with2026. -
2026.04.+— latest version starting with2026.04.(note: prefix matching is literal, including leading zeros) -
+— absolute latest version -
latest.release— same as+
Range syntax (e.g. [2026.0,2027.0)) is not supported. Use a prefix selector or a concrete version instead.
The selector is resolved at publish time by querying the Hytale Maven metadata for the configured patchline. The resolved concrete version (e.g. 2026.04.23-937872667) is what gets uploaded to Modtale, so your published mod stays pinned to a specific server build.
The modtale.patchline field controls which Hytale Maven repository the resolver queries:
-
patchline = "release"(default) resolves againsthttps://maven.hytale.com/release -
patchline = "pre-release"resolves againsthttps://maven.hytale.com/pre-release
patchline only affects dynamic selector resolution. When gameVersion is a concrete value it is uploaded as-is regardless of patchline.
Maven metadata is cached under <gradle-user-home>/caches/hytale-publisher/ for ten minutes to avoid repeated network calls during a publishing session. To force a fresh fetch (for example, immediately after a new server build is published), delete the cache file for your patchline:
# Linux / macOS
rm ~/.gradle/caches/hytale-publisher/maven-metadata-release.xml
# Or just clear the whole directory
rm -rf ~/.gradle/caches/hytale-publisherIf the network is unreachable but a cached copy exists, the resolver falls back to the cache with a warning. If nothing is cached and the network is down, publishing fails with a clear error rather than guessing.
Wildcard resolution does not require the Hytale Tools Gradle plugin to be applied. HytalePublisher fetches version metadata directly from the Hytale Maven, so you can use 2026.+ even in projects that build with a different toolchain.
