Platform Notes

Platform Notes

Modtale

• Uses gameVersion (defaults to project.hytale_version)
• Ensure your hytale_version matches a valid Modtale-supported version
• Accepts dynamic selectors like 0.+ — see Game Version for details
• Use modtale.patchline ("release" or "pre-release") to scope dynamic resolution to a specific Hytale Maven repo

CurseForge

• Uses numeric gameVersionIds
• Defaults to [14284] (Hytale Early Access)

Modifold

• gameVersions and loaders must be arrays.
• gameVersions must contain exact Hytale game version names, for example 0.5.0-pre.9.1.
• The old Early Access version category is no longer valid.
• If modifold.gameVersions is omitted, the plugin falls back to hytalePublisher.gameVersion / project.hytale_version.
• Multiple supported game versions can be uploaded at once.
• These are automatically JSON-encoded by the plugin
• Supports four dependency types via the DSL:
  • required(slug, versionId?) — the dependency is required for this build to work
  • optional(slug, versionId?) — the dependency is optional
  • incompatible(slug, versionId?) — this build is incompatible with the dependency
  • embedded(slug, versionId?) — the dependency is bundled inside this build
• The versionId argument is optional; omit it to allow any version of the dependency

Thunderstore

• Authentication uses Thunderstore service-account API tokens, not your user account. Generate one at: thunderstore.io -> Settings -> Teams -> [your team] -> Service Accounts.
• The package version must be SemVer (MAJOR.MINOR.PATCH). If your project version includes a qualifier like -beta, the plugin strips it for the Thunderstore manifest. Once a version is uploaded it cannot be reused, bump your version for every release.
• The plugin auto-generates manifest.json inside the zip from your DSL. You don't need to maintain a manifest in your repo, but you DO need:
  • icon.png (256x256 PNG) at the project root
  • README.md at the project root ...both are required by Thunderstore.
• hytalePublisher.changelogFile is bundled as CHANGELOG.md inside the package zip. If the file is missing, HytalePublisher creates it automatically. Existing changelog files are matched case-insensitively.
• The Hytale community slug is hytale. Browse available category slugs at: https://thunderstore.io/api/experimental/community/hytale/category/
• Content folder conventions match the Hytale Modding Thunderstore guides:
  • Plugins (.jar) -> mods/
  • Early plugins (.jar) -> earlyplugins/
  • Asset packs (.zip) -> mods/
  • Worlds -> worlds/
  • Universes -> universes/
  • Saves -> saves/
• Once a package is uploaded, its name and team are immutable. Triple check both before your first publish.

GitHub

• Creates a GitHub Release via the REST API. The release's tag_name is created automatically as part of creating the release — there's no separate tag/push step, and no way to publish a release without a tag (that's how GitHub Releases work).
• github.repository ("owner/repo") is optional. If omitted, it's auto-detected from the origin git remote (both SSH and HTTPS remote URLs are supported).
• The tag defaults to tagPrefix + projectVersion, e.g. v1.0.0. Override with github.tagPrefix.
• github.targetCommitish defaults to the current HEAD commit SHA (resolved via git rev-parse HEAD). Set it explicitly if publishing from a detached or shallow checkout where git commands might not resolve as expected — shallow checkouts (fetch-depth: 1) can still resolve HEAD, but full history (fetch-depth: 0) is recommended for reliability.
• Attaches the built jar, sources jar, and javadoc jar as release assets. Sources/javadoc are skipped with a warning (not a failure) if no sourcesJar / javadocJar task is found — this matches the task names produced by Gradle's java.withSourcesJar() / withJavadocJar().
• Additional files can be attached with asset("path/to/file"), resolved relative to the project directory unless given as an absolute path.
• releaseType values other than "release" (e.g. "beta", "alpha") automatically mark the GitHub release as a prerelease. Disable this with autoPrerelease = false, or force it with prerelease = true.
• Upload failures (4xx/5xx responses) fail the build immediately with the HTTP status code and full error body from GitHub.
• Workflow trigger caution: if your CI workflow triggers on release: types: [published] and you also enable github.enabled = true, publishing will try to create another release for a tag that already exists, which fails. Either trigger the workflow on push: tags / workflow_dispatch instead, or keep github.enabled = false in workflows meant to run in response to a release you already created manually.

Maven

• Uses Gradle's built-in maven-publish plugin under the hood rather than a custom uploader — maven.enabled = true applies that plugin automatically, so you don't need to add it yourself.

• maven.url is required. If maven.snapshotUrl is also set and the resolved version ends with -SNAPSHOT, that URL is used instead — the common release/snapshot repository split.

• groupId, artifactId, and version default to project.group, project.name, and hytalePublisher.version respectively. Override any of them individually if your published coordinates should differ from the project's own.

• Attaches the built jar by default. includeSourcesJar / includeJavadocJar attach sourcesJar / javadocJar task outputs if present, and are skipped with a warning (not a failure) otherwise — this matches Gradle's java.withSourcesJar() / withJavadocJar() task names, same as the GitHub target.

• Additional files can be attached with artifact("path/to/file"), resolved relative to the project directory unless given as an absolute path.

• The generated POM only includes what you set via pomName / pomDescription / pomUrl — it does not pull in your project's dependencies, since Hytale-mapped dependencies generally aren't resolvable through a normal Maven <dependencies> block anyway. For anything else (licenses, developers, SCM info), use the pom { } escape hatch, which is handed Gradle's MavenPom directly.

• Credentials are optional — if mavenUsername / mavenPassword (or their env equivalents) aren't set, HytalePublisher logs an info message and attempts to publish without credentials, which works fine for repositories that permit unauthenticated writes.

• allowInsecureProtocol must be set to true if your repository URL is plain http:// rather than https://. It defaults to false.

• Under the hood, publishToMaven is an alias for Gradle's auto-generated publish<PublicationName>PublicationTo<RepositoryName>Repository task, so it composes normally with other Gradle maven-publish tooling if you need it.

• Shadow plugin caution: if you use com.gradleup.shadow (or com.github.johnrengelman.shadow) and set shadowJar.archiveClassifier.set('') to make the shaded jar your "final" build output, shadowJar and the plain jar task now write to the same file. Gradle's task validation will fail with something like uses this output of task ':jar'/':shadowJar' without declaring an explicit or implicit dependency, because it can't tell which task actually produced the file being published. Fix it with two changes:

  • Set maven.jarTaskName = "shadowJar" so the plugin publishes (and depends on) the shaded jar rather than the plain one.
  • Give the plain jar task a distinct classifier so it no longer collides, e.g. jar { archiveClassifier.set('slim') }.

  This doesn't just silence the validation error — without it, there's a real risk of publishing the unshaded jar if task ordering ever shifts.