eco: The Spigot Framework Powering Minecraft Plugins

If you've ever wondered why certain Minecraft plugins feel smoother and more feature-rich than others, eco might be the answer. It's the underlying framework that powers some of the game's most polished plugins, handling everything from custom items to complex commands behind the scenes.

What's eco?

eco is a Spigot plugin framework, essentially a library of pre-built tools that plugin developers use to handle common tasks. Think of it as a set of blueprints. Every plugin needs certain things: a way to load configuration files, a command system, color support, and a method for storing player data. Instead of each developer writing these from scratch, eco provides them as ready-to-use APIs.

For server owners, the practical side is simple.

If a plugin depends on eco, you install eco as a separate plugin. No configuration needed (usually). It runs in the background and provides services to other plugins. The project has earned its place: with 220 GitHub stars and backing a whole ecosystem of popular plugins, it's become practically standard in the plugin development community.

Why So Many Developers Use eco

Here's where eco gets interesting. Plugin development without eco is tedious. You're constantly rewriting the same utilities: command argument parsing, configuration file handling, item NBT data manipulation, storage backends. Each plugin I've seen that reinvents these wheels ends up with inconsistent code and maintenance headaches down the road.

eco eliminates that overhead. A developer can focus on the actual plugin logic (the fun part) instead of plumbing.

The result is cleaner code, faster development, and fewer bugs. EcoEnchants, built on eco, has been installed across thousands of servers. Ditto for EcoItems, EcoSkills, EcoArmor, and Talismans. These aren't hobby projects. They're production-grade tools, and they exist because eco made building them feasible.

What specifically does eco provide?

• A modern command API that reads cleanly and handles argument parsing automatically
• Native color support including hex colors, RGB, and MiniMessage formatting
• Configuration handling for YAML, JSON, and TOML files
• Persistent data storage with support for local YAML, MySQL, and MongoDB backends
• A complete GUI system with pre-built components
• Custom item support with lookup strings so you don't have to deal with raw NBT
• An extension system (essentially plugins for plugins)
• Over 30 integrations with other popular plugins like economy systems and placeholders
• Full Kotlin support for developers who prefer it
• Math expression parsing for complex calculations

That's a lot, but the key insight is that none of these features are things developers want to spend time building.

Setting Up eco on Your Server

For server owners, installation is straightforward. Download eco from the GitHub releases page or from Polymart. Grab the latest stable version.

Place the eco JAR in your plugins folder:

cp eco-2026.25.jar ~/server/plugins/

Restart the server. eco will generate its config directory and load automatically. You don't need to configure eco itself unless you're doing something unusual like switching to MySQL for player data storage.

One thing to note: eco requires Minecraft 1.21.4 or newer (check the latest releases since this changes). If you're running an older version, you'll need to upgrade your server first.

Installing eco for Plugin Development

If you're building a plugin that uses eco, setup is more involved but still manageable. You need to add eco to your build system. Using Gradle (which is what most modern plugin projects use), you'd add the Auxilor repository and then declare eco as a dependency:

repositories {
    maven("https://repo.auxilor.io/repository/maven-public/")
}

dependencies {
    compileOnly("com.willfp:eco:2026.25")
}

Note that it's compileOnly, not a full implementation dependency. eco needs to be on the server at runtime, not bundled into your JAR.

Then declare eco as a dependency in your plugin.yml:

name: MyPlugin
version: 1.0.0
main: com.example.MyPlugin
depend:
  - eco

From there, you can import eco classes and start using its APIs. Want custom commands? Use eco's command framework. Need to store player data? Use its data layer. Want to integrate with other plugins? Use its hook system.

The Features That Make a Difference

eco has dozens of features, but a few stand out as genuinely time-saving.

Custom Items and Lookup Strings. Raw ItemStack data in Spigot is a nightmare. NBT tags, metadata, custom model data all scattered across different APIs. eco lets you define custom items once and reference them by name throughout your plugin. You write the definition, eco handles the details.

Flexible Configuration. Most Minecraft plugins are YAML-only. eco supports YAML, JSON, and TOML in the same plugin, and you can switch formats without rewriting code. Your server admins can choose their preferred format.

Database Abstraction. eco's data storage layer works with local YAML files, MySQL, or MongoDB. Write your persistence code once and let server admins choose the backend. That flexibility matters for plugins meant to scale.

The Command API. Parsing command arguments is repetitive and error-prone. eco's command system handles it automatically, with built-in support for argument types, completion, and permission checks.

Integrations. eco has out-of-the-box hooks for economy plugins, placeholder systems, and other major server tools.

Your plugin can expose data to the ecosystem without writing custom integration code. Real talk, and if you're managing a server with access control, our Whitelist Creator tool complements the kind of permission systems eco-based plugins can build.

Common Issues and How to Fix Them

Version Conflicts. If you're running multiple plugins that depend on eco but expect different versions, you might get errors. The fix: keep eco updated. One maintainers prioritize backward compatibility, so running the latest version usually means all your plugins work together.

Build vs. Runtime Confusion. Developers sometimes declare eco as a full implementation dependency instead of compileOnly. This leads to eco being bundled in the plugin JAR, which wastes space and can cause conflicts. Always use compileOnly.

Config Not Generating. eco generates default config files on first load. If you restart and a config isn't there, you might need a full server restart instead of just reloading the plugin.

Missing Repository. If your build fails with "repository not found", make sure you've added the Auxilor repository to your build.gradle. eco isn't on Maven Central, so your build needs to point to the right place.

Alternatives Worth a Look

eco dominates, but it's not the only framework out there. BukkitLib is lighter weight if your plugin only needs basic features. Some developers use raw Spigot APIs for simple plugins. There are also specialized frameworks for specific use cases (like economy plugins or GUI systems alone).

The tradeoff is usually time vs. features. eco gives you everything, but at the cost of a dependency. Raw Spigot APIs give you freedom but mean more work. For most plugins, eco is worth it. One caveat: eco sometimes lags a day or two after a new Minecraft version releases. If you need features from the absolute latest version immediately, you might need to wait. This rarely matters in practice.

If you're setting up a complex world with custom portals or dimensions (which some eco-based plugins do), our Nether Portal Calculator can help with the math on placement and spacing.

Before You Install

eco is stable, well-maintained, and used across thousands of servers. The maintainer has been active for years and takes backward compatibility seriously.

Server owners: installing eco is risk-free. It just adds a dependency layer. If a plugin works without eco, it'll work with eco installed.

Developers: learning eco is time well spent. The documentation is solid, the APIs are logical, and it'll make your plugins better. One maintainer actively develops the project and responds to community feedback. Major Minecraft versions trigger updates within days to support new blocks, items, and mechanics. You can follow updates on GitHub and check the changelog before upgrading.