Skip to main content
Multi-plugin stacks let you push several plugin JARs onto one Minecraft workload so you can test integration behavior in the same runtime that players connect to.

​
When to use plugins:

Use plugins: when the thing you need to validate depends on more than one plugin being present in the same Paper, Velocity, or gamemode server. Common cases:
  • A Velocity proxy plugin depends on another proxy plugin being installed.
  • A Paper plugin needs an economy, chat, teams, or permissions plugin in the same server.
  • A gamemode needs its runtime plugin plus support plugins in the same Agones-managed workload.
  • You want a shared release-default manifest that teammates can override with local plugin builds when debugging cross-plugin behavior.
For a single plugin push, keep using jar: instead.

​
Structured entries

Use structured plugin entries so release sources, local overrides, and push output all refer to the same stable plugin keys.
grounds.yaml
id is the stable key used for workspace overrides and source reporting. Keep it short, lowercase, and consistent across manifests and workspace configuration. variant identifies which artifact variant the stack expects. Use paper, velocity, or minestom depending on the plugin repository and workload. source is the portable default for plain grounds push. It should be something another developer or CI runner can resolve without your local filesystem.

​
Release defaults, local overrides

Keep release sources in grounds.yaml and put machine-specific paths in your local workspace config. That gives the team a reproducible default while still allowing local plugin replacement during development. Plain pushes use the release sources:
Push with every enabled local workspace override:
Push with selected local overrides:
When you pass --with-local, the CLI replaces enabled workspace entries for that push before Gradle uploads the bundle. Entries without a matching enabled workspace mapping continue to use their manifest source. See local plugin workspaces for scanning repositories, adding mappings, enabling variants, and checking which source each plugin will use.

​
Supported source forms

Each source resolves to one JAR before upload. The full manifest reference for source validation, GitHub release rules, and field behavior is in plugins.

​
Upload shape

groundsPush resolves every plugin entry to a JAR, packs the resolved files into one tar.gz bundle, and uploads that bundle as the push artifact. Forge unpacks the bundle into /app/plugins/ in manifest order. The bundle preserves load order with numeric prefixes because Paper and Velocity scan plugin directories from the filesystem. Put dependency plugins before the plugins that need them. The Gradle task reference has the lower-level upload details in Multi-plugin bundles.

​
Limits

  • plugins: and jar: are mutually exclusive. Pick one artifact shape per manifest.
  • plugins: requires 2 to 10 entries.
  • plugins: is supported for plugin-paper, plugin-velocity, and gamemode.
  • plugins: is not supported for service.
  • The total resolved upload is capped at 100 MB.
  • Local paths work, but they are not portable across machines or CI.

​
Next steps