Run Server

Run a local test server

Prove the plugin loads by booting a real Paper server matching the target mc_version, deploying the jar, and watching the log for the enable line. This skill takes heavier, real-world actions (downloading a server jar, running a Java server, accepting a license) — get explicit consent before doing them.

Phase 1: Load context & confirm a jar exists

• Read .mcplugin/config.yml for mc_version, version_scheme, java_version, platform, plugin_name, artifact_id, plugin_version. Missing → tell the user to run /setup-platform.
• Glob for the built plugin jar (target/<artifact_id>-<plugin_version>.jar or build/libs/*.jar). If none exists, stop and tell the user to run /build first (offer to hand off). If platform is velocity/bungeecord, note this skill boots a Paper server — a proxy needs a different setup — and confirm they still want a Paper test.
• Read ../../references/api/VERSION.md for version facts (Glob **/references/api/VERSION.md as fallback).

Phase 2: Get explicit consent (REQUIRED)

Use AskUserQuestion. Two things need a clear yes:

1. Download + run a server — "I'll download a Paper {{mc_version}} server jar (~50 MB) into a local run/ folder and start it briefly on this machine. OK to proceed?"
2. EULA — writing eula.txt with eula=true means you are accepting Mojang's EULA (https://aka.ms/MinecraftEULA). "Do you accept the Minecraft EULA?" Do not write the file or start the server until the user confirms both. If they decline the EULA, stop here.

Phase 3: Prepare run/

• Create a run/ directory in the project root and run/plugins/.
• Ensure run/ is gitignored (it holds a big server jar, worlds, logs). If .gitignore lacks it, Edit in a run/ line. Never commit the server jar or worlds.

Phase 4: Download the matching Paper build

Use the PaperMC downloads API. Verify the current endpoint with WebFetch before hardcoding — the 2026 year-based scheme may be served by a newer API (a v3 may exist); check https://docs.papermc.io/misc/downloads-api (or https://papermc.io/downloads/paper) for the target.

Classic v2 flow (works for 1.21.x; confirm for 26.x):

1. Builds for the version: WebFetch https://api.papermc.io/v2/projects/paper/versions/{{mc_version}}/builds — take the last entry (highest build), and its downloads.application.name (e.g. paper-1.21.4-131.jar).
2. Download URL: https://api.papermc.io/v2/projects/paper/versions/{{mc_version}}/builds/{build}/downloads/{name}

Download into run/ (choose by OS):

• bash/macOS/Linux: curl -fsSL -o run/paper.jar "<url>"
• Windows PowerShell: Invoke-WebRequest -Uri "<url>" -OutFile run/paper.jar
• (curl also ships on modern Windows if the user prefers one command.)

If the API returns 404 for the version, tell the user Paper has no build for that exact mc_version and suggest the nearest available one.

Phase 5: Accept EULA & deploy the jar

• After consent (Phase 2), Write run/eula.txt containing exactly:

  eula=true
  

• Copy the built plugin jar into run/plugins/ (cp / Copy-Item). Verify it landed (Glob run/plugins/*.jar).

Phase 6: Boot the server briefly, then stop it

Start Paper with the Java that matches java_version (a mismatch here reproduces UnsupportedClassVersionError). Run it in the background / time-boxed — never leave a server running. Pipe a stop in so it shuts down cleanly, or launch in background and stop after the enable line appears:

• bash/macOS/Linux (from run/): (sleep 45; echo stop) | java -Xmx2G -jar paper.jar --nogui
• Windows PowerShell (from run/): $p = Start-Process java -ArgumentList '-Xmx2G','-jar','paper.jar','--nogui' -PassThru -NoNewWindow; Start-Sleep 45; if(!$p.HasExited){ Stop-Process $p }

Prefer launching with run_in_background and polling the log, so you can stop as soon as startup completes rather than always waiting the full window. First boot downloads vanilla assets and generates a world — allow up to ~60–90s.

Phase 7: Read the log & report

Read run/logs/latest.log (Grep). Look for:

• Success: a line like [... INFO]: [{{plugin_name}}] Enabling {{plugin_name}} v... and a final Done (…)! For help, type "help" with no stack traces.
• Failure signals: Could not load 'plugins/...', UnsupportedClassVersionError (Java mismatch — recheck java_version), Invalid plugin.yml / main class not found (descriptor), ClassNotFoundException (unshaded dependency). Map each back to ../../references/pitfalls.md.

Report plainly whether the plugin loaded and enabled, quoting the relevant log lines. If it failed, give the specific fix and suggest /build (rebuild) or /plugin-review. Confirm the server was stopped. Leave run/ in place for the next test unless the user wants it cleaned.