Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grounds.gg/llms.txt

Use this file to discover all available pages before exploring further.

grounds.yaml lives at the root of your project and tells forge what you’re pushing. It’s read by both the Gradle plugin (to upload it) and forge (to build + deploy it).

​
Minimal example

grounds.yaml
name: my-plugin
type: plugin-paper
baseImage: paper

​
Full example

grounds.yaml
name: my-plugin
type: plugin-paper
baseImage: paper
jar: build/libs/my-plugin-*-all.jar
target: dev          # optional default; CLI/Gradle override wins
resources:
  cpu: 500m
  memory: 1Gi

​
Fields

​
name (required)

The logical app name. Used as:
  • The Kubernetes Deployment name (so it has to match [a-z0-9-]{1,40}).
  • The hostname prefix for staging previews (<name>-pr<id>.mc.grnds.io for Minecraft workloads, …dev.grnds.io for service).
  • The display name in the portal.
Once you’ve pushed, don’t rename — that creates a new app from forge’s perspective and orphans the previous one. Rename via portal or contact #grounds-platform if you need to migrate state.

​
type (required)

What kind of workload this is. One of:
TypeWorkloadBase image options
plugin-paperBukkit/Paper plugin JARpaper
plugin-velocityVelocity plugin JARvelocity
gamemodeBukkit/Paper plugin JAR running as an Agones-managed gameserverpaper-gamemode
servicePlain JVM app (no Minecraft runtime)service
type drives quotas, resource defaults, port mappings, and which container our renderer wires up.

​
baseImage (required)

The container base your JAR is layered onto. Must be one of the base images allowed for your type:
baseImageProvided byWhat it gives you
paperghcr.io/groundsgg/paperA Paper server with sane defaults, your JAR auto-loaded into plugins/. Use with type: plugin-paper.
paper-gamemodeghcr.io/groundsgg/paper-gamemodeSame as paper, but pre-bundled with plugin-agones-paper so the SDK sidecar (injected on every Fleet pod) reports Allocated/Ready from player events. Use with type: gamemode.
velocityghcr.io/groundsgg/velocityA Velocity proxy with your JAR in plugins/.
serviceghcr.io/groundsgg/jvm-serviceGeneric JVM runner — your JAR’s main is the entrypoint, no Minecraft runtime.
paper, paper-gamemode, and velocity versions are pinned by the base-image release. To bump (e.g., from 1.21.4 → 1.21.5), bump the base-image tag, not your manifest.

​
jar (optional, default build/libs/*.jar)

A glob pointing at the JAR to upload, relative to the project root. The Gradle plugin auto-detects shadowJar or jar and sets this for you, so you usually don’t need to write it. When to set it explicitly:
  • You produce multiple JARs and want to ensure the right one is picked.
  • You build with something other than shadowJar / jar.

​
target (optional)

A default target if neither the CLI flag nor the Gradle extension overrides it. Order of precedence:
  1. CLI flag: grounds push --target=staging
  2. Gradle extension: groundsPush { target.set("staging") }
  3. grounds.yaml: target: ...
  4. Fallback: dev
You almost never want this in version control — it makes “what does pushing actually do?” non-obvious for teammates. Prefer the CLI flag.

​
resources (optional)

CPU/memory request hints. They’re suggestions — forge clamps them to the per-type minimums (e.g., plugin-paper is at least 250m CPU and 1Gi memory) and to per-project quota maxima. If your value falls inside the legal range, it’s used as-is. 
resources:
  cpu: 500m       # Kubernetes resource units: 500m = 0.5 vCPU
  memory: 1Gi
Quirks worth knowing:
  • We always set requests == limits. Pods are deterministic and don’t burst.
  • Below the minimum: silently raised to the minimum.
  • Above the project quota: push fails at admission with a quota error.

​
agones (optional, gamemode only)

Agones-specific knobs. Only meaningful for type: gamemode, where the renderer wraps your workload in an Agones Fleet. Other types ignore the block. 
agones:
  replicas: 3
FieldDefaultRangeWhat it does
replicas11–20Number of GameServer replicas the Fleet keeps Ready. mc-router load-balances Minecraft traffic across them via the workload’s Service. Raise this when one game server can’t hold the player count you need; values above 20 require a platform-side quota bump.
The Agones SDK sidecar is injected by the cluster’s mutating webhook on every Fleet-managed pod, so plugin-agones-paper (and the Minestom/Velocity equivalents) can talk to localhost:9358 and report Allocated/Ready state from player events.

​
Other fields

grounds.yaml is strict. Unknown top-level fields are rejected at parse time so typos don’t silently get ignored. If you need something not covered here, open a #grounds-platform ticket — the parser only knows what’s listed above.

​
Validation

The Gradle plugin parses grounds.yaml before upload. Common errors:
ErrorFix
missing required field 'name'Add name.
field 'name' must be a stringQuote numeric-looking names.
'resources' must be a mappingMake sure it’s resources:\n cpu: … not resources: 500m.
unknown baseImage 'forge'Use one of the supported base images above.

​
Editor support

There’s no JSON Schema for grounds.yaml yet. On the roadmap; for now use this page as the reference. The Gradle plugin’s parse error messages name the offending field and line number.