Skip to main content
Local Minestom module substitution keeps release sources in grounds.yaml while you test local changes from sibling repositories. Use it when a server runtime and a module such as plugin-agones:minestom live in separate repositories.

​
Declare release modules

A Minestom server manifest declares portable release defaults that every developer and CI runner can resolve.
grounds.yaml
modules is CLI composition metadata. It tells grounds push which release modules can be replaced locally. Gradle dependencies still define the runtime classpath.
Keep source pinned to a release in shared manifests. Put local paths in workspace.yaml so the manifest stays portable.

​
Add a local module mapping

The mapping is stored in local workspace.yaml, not in the project manifest. workspace add also writes its generic JAR and shadowJar defaults, but the Minestom flow ignores those values and uses the repository path for Gradle composite-build substitution.

​
Push with local modules

Select one local module:
Use every enabled mapping that matches a modules entry:
For a Minestom push, the CLI loads the manifest and workspace mappings, resolves selected overrides, writes a temporary Gradle composite-build init script when needed, runs build.task, finds build.artifact, normalizes the distribution tar, and uploads that bundle to Forge.

​
Confirm effective sources

Local resolution prints the effective source table:
Use this table before reading build logs. It shows which modules came from local repositories and which stayed on release sources.

​
Explicit dependency substitution

Gradle composite builds usually substitute a local dependency automatically when the included build publishes the same coordinates as the release module. For an explicit substitution, add both module and project to the Minestom variant in workspace.yaml:
workspace.yaml
The CLI creates an init script equivalent to:
If one of module or project is configured, configure the other one too. The CLI rejects an incomplete substitution mapping before it runs Gradle.

​
Troubleshooting

If a release dependency is still used, run grounds workspace list, confirm the Minestom variant is enabled, then push with --with-local or the matching --local ID. If a selected local module is absent from grounds.yaml, add a matching modules entry or use its declared ID.