Set up Cursor Cloud dev environment

[CoasterFreakDE]

Description

Sets up and validates the Cloud Agent development environment for BasicX (a Kotlin Paper plugin built with Gradle). No product code was changed — the only tracked change is a new AGENTS.md documenting non-obvious build/run gotchas for future agents. The Cloud Agent update script warms the Gradle wrapper on startup (chmod +x gradlew + ./gradlew --version).

Verified the environment end-to-end:

• ./gradlew clean build --warning-mode all compiles (Java 25 toolchain auto-provisioned by the foojay resolver) and passes all 10 JUnit tests.
• Built Basicx-b5-SNAPSHOT.jar runs in a real Paper 26.2 server: it enables without exceptions, generates its YAML config files, and its console management commands work (basicx, basicx module disable/enable homes, basicx reload).

Run evidence (server log excerpt):
basicx_server_run.log

Type of change

• This change requires a documentation update

Checklist

• ./gradlew clean build --warning-mode all passes
• I tested affected behavior on Paper 26.2

Test plan

• Automated: ./gradlew build --warning-mode all --stacktrace — build successful, 10/10 tests pass.
• Paper smoke test: downloaded latest Paper 26.2 build, dropped the plugin JAR into plugins/, started with Java 25; confirmed BasicX enables in ~900 ms with no exceptions, generates config.yml/messages.yml/kits.yml/homes.yml/warps.yml, and responds to basicx, basicx module enable|disable, and basicx reload.

_{To show artifacts inline, enable in settings.}

  

[diffy-bot]

Added: AGENTS.md

Summary: New documentation file with Cursor Cloud / environment-specific notes for building and running the BasicX Paper (Minecraft) plugin. Covers build/test commands, Java toolchain quirks (important), network requirements, how to run the plugin on a Paper server, and recommended git-ignored paths.

Key points

• Purpose: Non-obvious environment gotchas for BasicX (Kotlin Paper plugin built with Gradle Kotlin DSL).
• Build & test:
  • Use Gradle wrapper: ./gradlew build (CI/full: ./gradlew clean build --warning-mode all).
  • No separate lint task; Kotlin compiler warnings are treated as errors (allWarningsAsErrors).
• Java toolchain (important):
  • Gradle wrapper runs fine on system Java 21 — you do not need to change JAVA_HOME to run the wrapper.
  • Project compiles targeting Java 25. Gradle will auto-provision a Temurin 25 JDK (~200 MB) via foojay on first build; JDK is placed under ~/.gradle/jdks/eclipse_adoptium-25-amd64-linux.*/.
  • First build also runs paperweightUserdevSetup (downloads/remaps Paper dev bundle). Both processes are cached thereafter.
  • Build requires network access to Maven Central and several Paper/mod-related repositories (repo.papermc.io, repo-api.modlabs.cc, repo.codemc.io, repo.helpch.at).
• Running the plugin (manual integration test):
  • Requires Paper 26.2 server; Paper 26.2 requires Java 25 to run (not just to compile).
  • Use the provisioned Java 25 binary (e.g. ~/.gradle/jdks/eclipse_adoptium-25-amd64-linux.*/bin/java) to start the server.
  • Recipe: download Paper 26.2 jar via Fill API, place in scratch dir, add eula=true to eula.txt, copy build/libs/Basicx-*.jar into plugins/, start with Java 25 (java -jar paper.jar --nogui).
  • On first enable the plugin downloads unshaded runtime libraries (Kotlin, coroutines, KPaper) and generates configuration files under plugins/BasicX/.
• Commands:
  • Console management: basicx, basicx reload, basicx module enable|disable <module>.
  • Player commands (require a connected client): /home, /tpa, /kit, etc.
• Repo hygiene:
  • Keep test server directories out of the repo. The repo already ignores /plugins/, /logs/, /world*/, /server/, /run/, /eula.txt.

Suggestions

• Network trust: The build and first-run steps download JDKs, Paper artifacts, and runtime libraries from external sources. Consider:
  • Pinning/checking versions and checksums for critical downloads (JDK, Paper builds, dependencies).
  • Verifying repository TLS and artifacts before running in sensitive environments.
• Path portability: The recommended Java 25 path relies on a wildcarded Gradle jdks directory. Consider documenting exact expected path or a helper script to locate the provisioned JDK to avoid confusion.
• Principle of least privilege: Remind users not to run servers or the build as root and to isolate test servers.
• EULA: Document the legal implication of writing eula=true and ensure test environments comply with Paper/Mojang requirements.

You can generate a new summary by commenting @diffy-bot

[diffy-bot]

Summary

Added new file AGENTS.md documenting Cursor Cloud-specific instructions and environment gotchas for the BasicX project (a Paper Minecraft server plugin).

TL;DR: BasicX is a Kotlin Paper plugin built with the checked-in Gradle wrapper. Builds run on the VM's Java 21 but compile/target Java 25 which Gradle will auto-provision. Running the plugin requires a Paper 26.2 server and Java 25. Network access to several Maven/Paper repos is required.

What changed

• New file: AGENTS.md (mode 100644)

Content highlights

• Project description

  • BasicX is a single-product repo: a modular Paper (Minecraft) server plugin written in Kotlin and built with Gradle (Kotlin DSL) using the checked-in wrapper.
  • Deliverable: plugin JAR in build/libs to be loaded by a Paper server.
  • Standard commands are in README.md, CONTRIBUTING.md, docs/SMOKE_TEST.md; AGENTS.md covers non-obvious environment gotchas.

• Build / lint / test

  • Build + unit tests (JUnit 5): ./gradlew build
  • CI/full check: ./gradlew clean build --warning-mode all
  • No separate lint task; build.gradle.kts sets allWarningsAsErrors → Kotlin compiler warnings fail the build.

• Java toolchain (important)

  • Gradle wrapper runs fine on VM default Java 21; you do not need to change JAVA_HOME to build.
  • Compilation targets Java 25. Gradle auto-provisions a Temurin 25 JDK via foojay on first build (~200 MB). Provisioned JDK path: ~/.gradle/jdks/eclipse_adoptium-25-amd64-linux.*/
  • First build also runs paperweightUserdevSetup (downloads/remaps Paper dev bundle, ~1 min). Both are cached afterwards.
  • Build requires network access to Maven Central, repo.papermc.io, repo-api.modlabs.cc, repo.codemc.io, and repo.helpch.at.

• Running the plugin end-to-end

  • Requires Paper 26.2 server; Paper 26.2 requires Java 25 to run (not just compile).
  • Use the provisioned Java 25 binary (example path shown) to run Paper.
  • Recipe:
    • Download latest Paper 26.2 jar from PaperMC Fill API
    • Put it in a scratch dir, write eula=true to eula.txt
    • Copy build/libs/Basicx-*.jar into plugins/
    • Start with Java 25: ~/.gradle/jdks/.../bin/java -jar paper.jar --nogui
  • On first enable the plugin downloads 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: basicx, basicx reload, basicx module enable|disable <module>
  • Player-facing commands require a connected client (e.g., /home, /tpa, /kit).

• Git ignore guidance

  • Keep test server directories in git-ignored paths. The repo ignores /plugins/, /logs/, /world*/, /server/, /run/, /eula.txt; do not commit server files or generated plugin data.

Suggestions

• Consider documenting checksums or provenance for the auto-provisioned Temurin 25 JDK and downloaded Paper artifacts, or noting how to verify them, since the build auto-downloads third-party binaries.
• Call out the security implication of runtime library downloads on plugin enable (if plugin pulls dependencies at runtime, explicitly warn about network/trust considerations).
• If reproducible builds are important, note the specific Paper build number or pin Maven coordinates to reduce variability when fetching latests.
• Consider adding an explicit note about where to find the Gradle wrapper and which wrapper version is used, so CI agents can be aligned.

You can generate a new summary by commenting @diffy-bot.