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.

./gradlew groundsTestLocal
Spins up a Paper or Velocity server on your laptop with this build’s plugin JAR pre-installed. The cloud equivalent is grounds push --target=dev; this is the offline development loop — no Grounds infra is touched, no quota is consumed, no cluster is needed.

​
When to use it

Use this whenUse grounds push --target=dev when
Iterating on plugin logic alone.You need the full forge runtime (eg. config plugin, social plugin) loaded.
Offline / on the train.You want to share with a teammate.
You don’t want to wait for a build + deploy round-trip.You’re testing inter-service interactions.
You’re new and not yet authed.You’re testing routing, ingress, or anything network-shaped.
For pure plugin-logic iteration, groundsTestLocal is 5× faster than a cloud push (no network upload, no Kaniko, no Kube reconcile).

​
Requirements

  • JDK 21+ on PATH.
  • An internet connection on the first run (to download Paper / Velocity from api.papermc.io). Subsequent runs are fully offline.

​
What happens

  1. Reads grounds.yaml, finds baseImage.
  2. If paper or velocity: downloads the latest stable build of that version from PaperMC’s v2 API. Caches under build/grounds-test/cache/.
  3. Sets up a server directory at build/grounds-test/<baseImage>-<version>/. Persists between runs, so player data + world chunks survive.
  4. For Paper: writes eula.txt (signed) and a sane server.properties on first run (online-mode=false, view-distance=8, no spawn protection). Edits stick.
  5. Drops your plugin JAR into plugins/.
  6. java -jar starts the server with stdin/stdout attached. Ctrl-C shuts it down cleanly.

​
Output

> Task :groundsTestLocal
[grounds-test] downloading paper-1.21.4-220.jar from PaperMC
[grounds-test] installed my-plugin-0.1.0-all.jar into …/plugins
[grounds-test] starting Paper 1.21.4 in …/build/grounds-test/paper-1.21.4
[grounds-test] connect with: minecraft://localhost:25565 (paper) or 25577 (velocity)
[server thread/INFO]: Starting Minecraft server on *:25565
…
Connect from your client to localhost:25565 (Paper) or localhost:25577 (Velocity).

​
Configuration

build.gradle.kts
groundsPush {
    paperVersion.set("1.21.5")              // default 1.21.4
    velocityVersion.set("3.4.0-SNAPSHOT")   // default
}
Versions are resolved against PaperMC’s v2 API at task run time, so any version they publish is fair game.

​
Limitations (v0)

  • Only baseImage: paper and baseImage: velocity are supported. minestom and service workloads need grounds push --target=dev — they’re plain JVM apps, not Minecraft servers, and we don’t ship a generic local runner.
  • No multi-plugin compose. Only this build’s JAR gets auto-installed; if you manually drop other JARs into plugins/, they’ll persist between runs (the task only re-installs its own JAR each time).
  • Local data is just a directory. Wipe with ./gradlew clean (or rm -rf build/grounds-test/) for a fresh world.

​
What does not happen

  • No Kaniko build. Your raw JAR is loaded directly — same as ./gradlew build then dropping it manually into a Paper server’s plugins/.
  • No quota / push-history record. This task talks to no Grounds infra.
  • No public URL. It’s localhost. Use staging if you need a sharable URL.

​
Combining with groundsPush

A reasonable inner-to-outer-loop:
  1. ./gradlew groundsTestLocal — iterate locally until it works.
  2. grounds push --target=dev — verify it works inside the platform’s runtime (config plugin, social plugin, etc.).
  3. grounds push --target=staging — share with a teammate.
  4. grounds promote <pushId> — release.