Yoko — Lightweight Spigot/Paper Plugin Dev Tool

Yoko is a small CLI tool to help scaffold, hydrate and build Spigot / Paper Minecraft plugins. It automates:

• creating a new plugin skeleton,
• fetching PaperMC server builds and Spigot API jars,
• resolving Maven dependencies from configurable repositories,
• downloading suitable JDKs from Adoptium if missing,
• creating a ready-to-use local dev server and VS Code configuration,
• building, packaging and running a debug-ready server for development.

Written in Go and intended to be a tiny, focused developer utility for plugin authors.

---

Table of Contents

• Features
• Requirements
• Installation
• Basic usage
• Commands
  • init
  • hydrate
  • build
  • test
  • clean
• project.json (project configuration)
• Caching & JDKs
• VS Code integration
• Notes & Troubleshooting
• Development
• License

---

Features

• Scaffold a new plugin project with source and plugin.yml template.
• Download and cache PaperMC server jars and Spigot API (shaded) jars.
• Resolve and download Maven dependencies (including snapshot handling).
• Auto-download Adoptium JDKs for supported Java versions (8, 17, 21).
• Build and package plugin.jar to .yoko/plugin.jar.
• Start a dev server and attach a Java debugger for iterative development and reloads.
• Create VS Code settings, tasks and launch configuration for quick start.

---

Requirements

• Go toolchain to build the tool (testing/building the tool itself).
  • go 1.22 (module uses go 1.22)
• Network access to:
  • api.papermc.io
  • repo1.maven.org (and any additional repos you configure)
  • api.adoptium.net (for JDK downloads)
• Java (Yoko will download JDKs automatically when needed if allowed)
• A terminal that supports ANSI colors is recommended for best UX.

---

Installation

Clone and build:

git clone https://github.com/Complexicon/yoko.git cd yoko go build -o yoko main.go

(Alternatively run go install ./... to install into your $GOBIN.)

Note: the repository's go.mod specifies go 1.22 and a few dependencies (cobra, promptui, progressbar, etc).

---

Basic usage

Yoko exposes a small set of commands. Run ./yoko --help or ./yoko <command> --help for help.

Primary workflow:

1. yoko init — scaffold a new plugin (creates project.json, source, plugin.yml).
2. yoko hydrate — download server, API, dependencies and configure VS Code + dev server.
3. yoko build — compile and package plugin.jar into .yoko/plugin.jar.
4. yoko test — build, copy plugin to .yoko/server/plugins and start server with debug agent attached (suspend), watching for source changes to rebuild & reload.
5. yoko clean — remove compiled class files (.yoko/classes).

---

Commands

• init Scaffold a new plugin project interactively. It asks:

  • plugin name
  • group ID (e.g. dev.cmplx)
  • Minecraft version (listed from PaperMC)

  init writes:

  • project.json
  • src/main/java///Main.java
  • src/main/resources/plugin.yml

  After scaffolding it runs hydrate automatically.

• hydrate Ensure the requested Minecraft version is available and cached. It:

  • verifies the version against papermc API,
  • downloads server JAR, spigot-api shaded jar and sources,
  • prompts to accept the Minecraft EULA, writes .yoko/server/eula.txt,
  • prepares a local server directory under your user cache dir (by default ~/.yoko),
  • downloads and caches repository dependencies into ~/.yoko/libs,
  • writes VS Code settings.json, tasks.json and launch.json into .vscode,
  • runs a first build.

• build Compiles Java sources under src/main/java and writes classes to .yoko/classes and produces .yoko/plugin.jar. Flags:

  • --release: Build without debug symbols (omit -g). Default builds include debug info.

• test Build, copy plugin to the dev server plugins folder and start the server with the JDWP debug agent:

  • uses -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 The server will suspend and wait for a debugger to attach. test also watches source files; when a change is detected, it will recompile, copy the plugin and send a reload confirm to the server.

• clean Remove compiled class files: deletes .yoko/classes

---

project.json (project configuration)

Yoko expects a simple JSON file named project.json in the project root. The fields:

{
  "name": "MyPlugin",
  "minecraftVersion": "1.20.1",
  "mvnRepos": ["https://my.custom.repo/repo/"],   // optional additional mvn repos
  "dependencies": [
    {
      "groupID": "org.example",
      "artifact": "examplelib",
      "version": "1.0.0"
    }
  ]
}

Dependencies are resolved via groupId:artifact:version (maven-style). Snapshots are supported when you specify a version that ends with "-SNAPSHOT".

Example to add a dependency:

• Add the entry to project.json dependencies, then run yoko hydrate or yoko build — Yoko will download the jars to the local cache and include them on the classpath.

---

Caching & JDKs

• User cache dir is set to ~/.yoko by default
• Paper server jars are cached at: ~/.yoko/server/server-.jar
• API jars and sources are cached at: ~/.yoko/api/api-.jar, src-.jar
• Maven dependencies are cached at: ~/.yoko/libs/.-.jar
• JDKs are downloaded into ~/.yoko/java8, ~/.yoko/java17, ~/.yoko/java21 (depending on Minecraft version needs).

JDK downloads are performed using the Adoptium API. Yoko will prompt before downloading missing JDKs unless you pass --install-jdks.

---

VS Code integration

hydrate creates/updates .vscode/settings.json, .vscode/tasks.json and .vscode/launch.json:

• settings.json:

  • sets java.project.sourcePaths
  • sets java.project.referencedLibraries to include produced dependency jars and the spigot api jar
  • sets java.configuration.runtimes to include the JDK path for the chosen MC version

• tasks.json:

  • a build-and-run task is created. Yoko patches the task command to point to the yoko executable so running the task will call yoko test.

• launch.json:

  • a Java attach configuration is present to attach to the default address 5005 used by yoko test.

---

Notes & Troubleshooting

• EULA: hydrate prompts you to accept the Minecraft EULA and writes eula.txt in the server cache. You must accept it to run the dev server.
• Network/Firewall: ensure outbound HTTP(S) is permitted for api.papermc.io, repo1.maven.org and api.adoptium.net.
• Snapshot dependencies: Yoko will attempt to read maven-metadata.xml for snapshot timestamps/build numbers when downloading snapshot artifacts.
• If a required JDK can't be found or downloaded automatically, inspect ~/.yoko for the java* directories or provide your own JDKs by creating those directories and installing a compatible JDK.
• Debugging port: yoko test uses port 5005. Ensure nothing else is listening on that port.
• Platform differences: on macOS the JDK home used by Yoko points to /Contents/Home when required by tooling.

---

Development

• The code is organized into:

  • cmd/ — cobra CLI commands and embedded templates
  • util/ — common utilities (downloading with progress, prompts, project config parsing, Java selection)
  • papermc/ — PaperMC API client
  • maven/ — maven artifact parsing and repository lookup
  • adoptium/ — JDK download and unpacking
  • globals/ — global runtime variables (cache path, jdk paths)

• Run and test locally: go build ./... ./yoko --help

• The code uses Go modules. Use go mod tidy if you add dependencies.

---

Examples

Create and start a project interactively:

./yoko init

Download required JDKs automatically (no prompts) while hydrating/building:

./yoko --install-jdks hydrate

Build without debug symbols:

./yoko build --release

Start a debug server (build + watch + suspend waiting for debugger):

./yoko test

---

Acknowledgements & External APIs

• PaperMC API (api.papermc.io) for version / build lookup
• Maven Central and other Maven repositories for dependency artifacts
• Adoptium API for JDK downloads
• Uses libraries:
  • cobra (CLI)
  • promptui (interactive prompts)
  • progressbar/v3 (progress bars)
  • mitchellh/colorstring (colored terminal output)