# ACF turns a Minecraft command handler into a set of annotated methods > The Annotation Command Framework takes the boilerplate that fills every command class, dependency injection, validation, tab completion, help pages, syntax advice and stateful conditions, and moves it behind annotations on methods. It started as a Bukkit plugin framework and is now usable on any Java application, with per platform artifacts for Paper, Spigot, Sponge, BungeeCord, JDA and Velocity, and it still carries a beta label with API breakage expected. **aikar/commands** — Java Command Dispatch Framework - (Bukkit, Spigot, Paper, Sponge, Bungee, JDA, Velocity supported, generically usable anywhere) - Repository: https://github.com/aikar/commands - Website: https://acfspigot.emc.gs - Stars: 628 · Forks: 151 - Language: Java - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/aikar-commands ## The framework started on Empire Minecraft and then became platform agnostic The origin explains a lot about the design. ACF is the command framework originally created for Empire Minecraft, and it started as a Bukkit command framework but has shifted to be platform-agnostic and can be used on any Java based application. That history is visible in the repository layout, which still carries a bukkit directory, a paper directory, a sponge directory alongside sponge10, a bungee directory, a jda directory and jda5, a velocity directory, a core directory and a brigadier directory, plus languages for localisation and an example project. The description names the supported surfaces as Bukkit, Spigot, Paper, Sponge, Bungee, JDA and Velocity, with the caveat that it is generically usable anywhere. So the framework is not a Minecraft plugin library that happens to be portable, it is a general command dispatch layer that grew up inside a Minecraft server and kept its platform modules as adapters. ## Six platform artifacts, and Paper is the one to pick The dependency you add is decided by your platform, and the artifact id varies accordingly. The group is co.aikar, the documented version is 0.5.1-SNAPSHOT, and the artifacts are acf-bukkit for targeting Bukkit or Spigot, acf-paper which is recommended over Bukkit, acf-sponge, acf-bungee, and acf-jda5 which is marked INCOMPLETE and MINIMALLY IMPLEMENTED. The Paper artifact is described as gradually enhancing when run on Paper while still running on Spigot, which is the practical meaning of that recommendation. The documentation also notes that you may include more than one platform in your jar if your plugin supports multiple platforms, so the cost of targeting several surfaces is one extra dependency rather than a fork. The velocity directory in the tree suggests the newest platform target has been added without the older ones being removed, and the jda and jda5 pair suggests the Discord adapter went through a rewrite. ## Everything a command handler repeats becomes an annotation This is the core claim, and it is worth reading precisely. ACF is described as an extremely powerful command framework that takes nearly every concept of boilerplate code commonly found in command handlers and abstracts them away behind annotations. The framework redefines how you build command handlers, allowing things such as Dependency Injection, Validation, Tab Completion, Help Documentation, Syntax Advice, and Stateful Conditions to all be behind annotations that you place on methods. The six items are the substance of the library, not marketing. Dependency injection means a handler can ask for a service rather than look one up. Validation means a parameter can declare what it accepts. Tab completion means the same declaration can drive the completion list. Syntax advice means a wrong argument produces a usage message rather than a stack trace. Stateful conditions mean a command can require a prior command to have run. Help documentation means the usage text is generated from the same annotations. ## Documentation lives entirely in the GitHub wiki, not in the repository This is worth knowing before you start, because it changes where you will spend your first hour. All of ACF's documentation is currently on the GitHub Wiki, and the README asks you to review every page to learn about each feature. Two pages are singled out: Using ACF, which covers how to add ACF to your plugin and how to get started, and Real-World-Examples, which is a set of real world examples. The setup guides for dependencies are separate pages too, a Maven setup guide and a Gradle setup guide, and they are the ones you need because the repository does not carry a copy of the build configuration you would copy. The JavaDoc links are also per module, with separate pages for the core, Bukkit, Sponge, Bungee and JDA builds. The consequence is that learning this framework is a wiki-reading exercise, and the wiki is a place that can lag behind the code without anyone noticing. ## The 0.x.x label means version bumps break your code The beta section is unusually candid and is the most important thing to weigh before adopting the library. While the 0.x.x series is Beta, the note says it is very stable and has been used for years on Empire Minecraft. The reason it is labelled beta is that the framework is growing and gaining new features, and APIs are subject to breakage, with new features possibly containing bugs. The mitigation is a version policy, because any bump in version implies an API break, and the CHANGELOG holds migration guides for those breaks, while every change that should not cause an API break is deployed over the current version. The release target is stated plainly: v1.0.0 will be the signal that ACF features are more complete and the API will remain stable for a long time. The branch naming is also a signal, since branches prefixed with dev/ indicate something likely to be very unstable, possibly completely non-functional, and may not even have the new changes implemented on that branch yet. ## Adding the dependency: Maven and Gradle guides live in the wiki The repository does not contain an install command for you to copy, and the documentation points at the wiki pages instead. The setup guides for the repository and its requirements are separate documents, a Maven setup guide and a Gradle setup guide, and the Using ACF page covers how to add ACF to a plugin and get started. The repository does ship an example project with its own pom.xml under example/, and a top-level pom.xml for the framework itself, so the practical approach for most users is to read the wiki page, add the co.aikar group and the platform artifact you need, and then compare against the example project. The example project is the more useful of the two references for a new user, because it shows the dependency and the annotations together, which is what the wiki page on getting started is really about. The repository also includes a deploy.sh script and a .travis.yml file, which belong to the framework's own build and release process rather than to your plugin. ## How ACF compares with writing the handler yourself The honest comparison is not with another framework so much as with the alternative of not having one. Writing a command handler by hand means you implement parsing, type conversion, permission checks, usage text and completion separately, and then you maintain them. ACF takes that work and moves it into declarative annotations on your methods, so the handler becomes a method signature and a body. The cost is the learning curve and the version policy described earlier. A second comparison is with Brigadier, which appears as a directory in the repository tree, and the difference is that Brigadier is a parser for command syntax, while ACF is a framework around the whole handler, adding injection, validation, help generation and platform integration on top. So the two are not alternatives in the same sense, and the presence of both in the tree is a sign of layering rather than duplication. For a Java application outside Minecraft, ACF's value depends on how many commands you have and how much of the boilerplate you would otherwise write. ## Where ACF is the wrong choice The first wrong case is a project with a handful of commands and simple arguments, where a hand-written handler is shorter than the annotation setup and where the generated help and completion features save nothing. The second wrong case is a team that needs a stable API now, since the project states plainly that any version bump implies an API break and that v1.0.0 is the signal for long-term stability, which makes the framework a moving target you would upgrade deliberately rather than continuously. The third is a JDA-based Discord bot that needs full command support, because the acf-jda5 artifact is marked incomplete and minimally implemented, so the JDA path is not where the framework's depth is. The fourth is a team that has decided against a dependency on a Minecraft-adjacent project, since the core is usable on any Java application but the whole package set is published under a co.aikar group with the surrounding ecosystem of Aikar and Empire Minecraft projects, and a procurement or review process may look at that differently from a generic library. ## Conclusion Plugin authors on Paper or Spigot who have a command layer full of repeated boilerplate, and teams building a Java application with a command interface that needs validation and help output, are the people ACF is for, and the fact that the same annotations work on Paper, Sponge, BungeeCord, JDA and Velocity is what makes it worth the learning curve. It is the wrong choice for a project that needs a stable API today, because the documentation says the 0.x.x series is beta and that any version bump implies an API break, and it is the wrong choice for a small command surface where hand-written handlers would be shorter than the configuration. Check three things before you commit: which platform artifact you need, since the JDA variant is marked incomplete and minimally implemented while Paper is the recommended target over Bukkit, what the current version number means for you, since the documented version is a snapshot and the project states that v1.0.0 is the signal that the API will remain stable for a long time, and how the CHANGELOG migration guides read for the bump you are about to take. The licence is MIT, the last push was on 2026-05-11, and the repository publishes no GitHub releases. ## FAQ ### Which ACF artifact should I add to my project? It depends on your platform: acf-bukkit for Bukkit or Spigot, acf-paper which is recommended over Bukkit, acf-sponge, acf-bungee, and acf-jda5 for JDA, which is marked incomplete and minimally implemented. The group is co.aikar, and you may include more than one platform in your jar if your plugin supports several. ### Is ACF ready for production use? The documentation describes the 0.x.x series as Beta but very stable, and as having been used for years on Empire Minecraft. The reason for the label is that the framework is growing and its APIs are subject to breakage, and the project states that v1.0.0 will signal that the API will remain stable for a long time. ### Where can I find the ACF documentation? All of the documentation is on the GitHub Wiki, and the README asks you to review every page. The Using ACF page covers adding ACF to your plugin, the Real-World-Examples page has worked examples, and there are separate Maven and Gradle setup guides, while the JavaDoc is published per module. ### What happens when an ACF version changes? Any bump in version implies an API break, and the CHANGELOG holds the migration guides for those breaks. Changes that should not cause an API break are deployed over the current version, and branches prefixed with dev/ are explicitly unstable and may not even contain the newest changes. ### What licence is ACF released under? MIT, as stated in the readme and in the LICENSE file, with the copyright line naming Daniel Ennis (Aikar) and the years 2016 to 2022. The last push was on 2026-05-11 and the repository publishes no GitHub releases. ## Sources - [aikar/commands on GitHub](https://github.com/aikar/commands) - [Issues](https://github.com/aikar/commands/issues) - [License: MIT](https://github.com/aikar/commands/blob/master/LICENSE) - [Project website](https://acfspigot.emc.gs) - [README](https://github.com/aikar/commands/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aikar-commands