Skip to main content
Local Minestom module substitution lets you keep release module sources in grounds.yaml while testing local changes from sibling repositories. Use this when your server runtime is in one repository and a runtime module, such as plugin-agones:minestom, is in another repository.

​
Manifest modules

A Minestom server manifest declares the release defaults that every developer and CI runner can resolve.
grounds.yaml
name: minigame-agones
type: minestom-server
baseImage: minestom
build:
  task: :examples:minigame-agones:distTar
  artifact: examples/minigame-agones/build/distributions/*.tar
modules:
  - id: plugin-agones
    variant: minestom
    source: github:groundsgg/plugin-agones@v0.6.0:plugin-agones-minestom.jar
modules is CLI composition metadata. It tells grounds push which release modules can be replaced locally. Your Gradle dependencies still define the actual 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

Add a local repository mapping for the Minestom variant: 
grounds workspace add plugin-agones ~/grounds/plugin-agones --variant minestom
The mapping is stored in your local workspace.yaml, not in the project manifest.

​
Push with local modules

Use --local for selected modules: 
grounds push --local plugin-agones
Use --with-local for every enabled workspace entry that matches a modules entry: 
grounds push --with-local
For Minestom pushes, the CLI:
  1. loads grounds.yaml;
  2. resolves selected local module mappings from workspace.yaml;
  3. writes a temporary Gradle composite-build init script;
  4. runs the configured build.task, such as :examples:minigame-agones:distTar;
  5. finds the configured build.artifact;
  6. normalizes the distribution tar;
  7. uploads the normalized distribution to Forge.

​
Effective source table

When local module resolution runs, the CLI prints the effective source table: 
Bundle sources:
ID              Variant   Effective   Value
plugin-agones   minestom  local       /home/alice/grounds/plugin-agones
Use this table as the confirmation step before reading build logs. It shows which modules came from local repositories and which modules stayed on release sources.

​
Explicit dependency substitution

Gradle composite builds often substitute dependencies automatically when the local included build publishes the same module coordinates as the release dependency. When a repository needs explicit substitution, add module and project to the Minestom variant in workspace.yaml: 
repos:
  plugin-agones:
    path: /home/alice/grounds/plugin-agones
    variants:
      minestom:
        enabled: true
        module: gg.grounds:plugin-agones-minestom
        project: :minestom
The CLI then writes a Gradle init script equivalent to: 
settingsEvaluated {
    includeBuild("/home/alice/grounds/plugin-agones") {
        dependencySubstitution {
            substitute(module("gg.grounds:plugin-agones-minestom")).using(project(":minestom"))
        }
    }
}
If module is set, project must also be set. If only one field is present, the CLI fails before running Gradle.
For Minestom module substitution, the app’s Gradle distribution task builds against the included local repository. The workspace artifact and build fields are used for plugin artifact overrides and are not the source of truth for the Minestom runtime classpath.

​
Troubleshooting

Check grounds workspace list and confirm the plugin-agones minestom variant is enabled. Then run grounds push --with-local or grounds push --local plugin-agones.
--local <id> must match an entry under modules. Add the module to grounds.yaml or use the correct module ID.