From 91f5f2a6da8c91390e1d51d4e7e8c41f2c2c1419 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 15 Jul 2026 21:24:58 +0000 Subject: [PATCH] Add AGENTS.md with Cursor Cloud setup and run instructions Co-authored-by: Liam Sage --- AGENTS.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3c27b34 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,22 @@ +# AGENTS.md + +## Cursor Cloud specific instructions + +BasicX is a single-product repo: a modular **Paper (Minecraft) server plugin** written in Kotlin and built with Gradle (Kotlin DSL) via the checked-in wrapper. There is no long-running dev server — the deliverable is a plugin JAR in `build/libs` that is loaded by a Paper server. Standard commands live in `README.md`, `CONTRIBUTING.md`, and `docs/SMOKE_TEST.md`; the notes below only capture non-obvious environment gotchas. + +### Build / lint / test +- Build + unit tests (JUnit 5): `./gradlew build` (CI/full check: `./gradlew clean build --warning-mode all`). +- There is no separate lint task. `build.gradle.kts` sets `allWarningsAsErrors`, so any Kotlin compiler warning fails the build — treat compiler warnings as lint failures. + +### Java toolchain (important gotcha) +- The Gradle wrapper itself runs fine on the VM's default **Java 21**; you do not need to change `JAVA_HOME` to build. +- Compilation targets **Java 25**, which Gradle auto-provisions via the foojay resolver on the first build (downloads a Temurin 25 JDK, ~200 MB). The provisioned JDK lands under `~/.gradle/jdks/eclipse_adoptium-25-amd64-linux.*/`. +- The first build also runs paperweight `paperweightUserdevSetup` (downloads + remaps the Paper dev bundle, ~1 min). Both are cached, so only the first build in a fresh environment is slow. +- Network access to Maven Central, `repo.papermc.io`, `repo-api.modlabs.cc`, `repo.codemc.io`, and `repo.helpch.at` is required at build time. + +### Running the plugin end-to-end (manual integration test) +- To actually run the plugin you need a Paper **26.2** server, and Paper 26.2 requires **Java 25 to run** (not just to compile). Use the provisioned toolchain JVM, e.g. `~/.gradle/jdks/eclipse_adoptium-25-amd64-linux.*/bin/java`, not the default `java` (21). +- Recipe: download the latest Paper 26.2 jar from the PaperMC Fill API (`https://fill.papermc.io/v3/projects/paper/versions/26.2/builds/latest`), put it in a scratch dir, write `eula=true` to `eula.txt`, copy `build/libs/Basicx-*.jar` into `plugins/`, then start with the Java 25 launcher (`java -jar paper.jar --nogui`). +- On first enable the plugin downloads its unshaded runtime libraries (Kotlin, coroutines, KPaper) via Paper's isolated library loader and generates `plugins/BasicX/{config.yml,messages.yml,kits.yml,homes.yml,warps.yml}`. +- Console management commands (no player needed): `basicx`, `basicx reload`, `basicx module enable|disable `. Player-facing commands (`/home`, `/tpa`, `/kit`, etc.) require a connected client. +- Keep any test server in a directory that is git-ignored (the repo ignores `/plugins/`, `/logs/`, `/world*/`, `/server/`, `/run/`, `/eula.txt`); do not commit server files or generated plugin data.