Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

pluggy docs

pluggy is a self-contained toolchain for Minecraft plugin development. Scaffold a project, install dependencies from Modrinth, Maven, local jars, or sibling workspaces, build a real plugin jar, and boot a live Paper, Spigot, Velocity, or Sponge server that rebuilds when you save.

No global JVM toolchain, no Gradle wrapper, no pom.xml. One project.json per project.

Start here

If you have never used pluggy before, read these in order. The first page is enough to get a plugin running.

  • Getting started: install, scaffold, build, and run a dev server. Eight minutes from zero to a live server.
  • Glossary: plain-English definitions for every term in these docs. Bookmark it.
  • project.json reference: every field, every form, and the validation rules.
  • Dependency sources: the Modrinth, Maven, file, and workspace grammar.

Commands

Every subcommand, with its flags, JSON envelope, and sample output.

Command Summary
init Scaffold a new project in an empty directory.
install Add a dependency or refresh the lockfile.
remove Drop a dependency and (optionally) its cached jar.
info Inspect a Modrinth, Maven, file, or workspace source.
search Search Modrinth by keyword.
list Print declared deps, resolved versions, and registries.
why Trace which top-level dep pulled in a transitive.
outdated List locked deps with a newer upstream version.
audit Verify cached jars against the lockfile hashes.
build Compile, copy resources, write the descriptor, jar.
test Compile and run JUnit Platform tests under test/.
docs Generate Javadoc HTML against the resolved classpath.
dev Boot a live server with the plugin and its runtime deps.
run Invoke a named script across the selected workspaces.
clean Remove bin/ build outputs across workspaces.
workspaces List every workspace's role, platforms, and output path.
workspace Add, remove, or rename a workspace.
graph Render the workspace dependency graph.
explain Show one workspace's post-inheritance view.
sdk Manage the JDKs pluggy provisions for builds.
cache Inspect and prune the download cache.
doctor Check the environment and every workspace.
upgrade Replace the running binary with the latest release.
completions Print a shell completion script.

Deeper topics

These pages explain how pluggy works once you've outgrown the tutorial. They assume you've shipped at least one plugin.

  • Build pipeline: what happens between pluggy build and the output jar. Maven dependency resolution, SNAPSHOT handling, classpath construction, descriptor generation.
  • Dev server: the dev/ staging directory, runtime vs compile-time plugin detection, EULA handling, --reload vs restart, shutdown semantics.
  • Workspaces: monorepo layout, inheritance rules, the workspace: source kind, topological build order.
  • IDE integration: what ide: "vscode" | "eclipse" | "intellij" writes and where.
  • Cross-platform notes: install paths, cache paths, line endings, signal handling.
  • Troubleshooting: common failures, the error messages the code actually prints, and what to do about them.
  • Uninstalling: exact paths to remove for each install method, plus the cache and state directories.

Recipes

Task-oriented walkthroughs for situations that come up often. Each recipe stands alone; pick the one that matches what you're trying to do.

Reading these docs

Path examples use POSIX form (~/Library/Caches/pluggy/...). When the Windows path differs in a way that matters, the difference is called out inline.

pluggy reads one file (project.json) and writes one lockfile (pluggy.lock). Everything else, the cache, the build staging directory, the dev/ server directory, is derived from those two.

If a term feels unfamiliar, check the glossary first.