I Built 7 Free Minecraft Plugins in a Weekend

The setup

I run a Minecraft economy survival server. A small one. The kind where most plugins on the marketplace are either over-engineered for a 60-player community or have a config that takes longer to write than just rebuilding the feature from scratch.

So I rebuilt seven of them from scratch. Each one targets exactly the thing I needed and skips the rest. They're MIT-licensed and they're all on github.com/astroworld-mc. They run on Paper 1.20+, Spigot, and Purpur.

This post is the story of building them. What each one does, why I bothered when there's already something on SpigotMC for it, and the lessons that repeated across all seven.

The seven

AstroSimpleAFK. Detects idle players and tags them with [AFK] in the tab list. Most AFK plugins I tried also did "AFK kick after 20 minutes" with a permission tree five levels deep and a database. I just needed tab-list status and a /afk toggle.

AstroCustomMOTD. Custom MOTD with a random rotation of taglines and a one-line maintenance mode that flips the MOTD plus rejects non-staff joins. Existing MOTD plugins layer this with %placeholders% and a NodeJS-style config DSL. Mine is 6 lines of YAML.

AstroJoinLeave. Per-group join and leave messages with optional welcome titles for first-time joins. Hooks LuckPerms if it's there; falls back to a single message group otherwise.

AstroPlayerStats. SQLite-backed stats (playtime, joins, kills, deaths, blocks broken, blocks placed) with %astrostats_*% PlaceholderAPI placeholders. No web dashboard. The stats live in the bot and a Discord embed.

AstroAutoSave. Periodic save-all with broadcast warnings ("Server saving in 30 seconds…"). Vanilla autosave isn't broadcast and most server owners don't realize the lag spike comes from it.

AstroBackCooldown. Per-LuckPerms-group cooldowns on the Essentials /back command. Default group: 30 seconds. VIP: 10 seconds. Staff: no cooldown. Three lines of YAML.

AstroChatBot. Keyword-matching chat bot that responds to player questions. Player types "how do i set home", bot replies "/sethome ". Configurable per-keyword cooldown so it doesn't spam. Supports multiple languages by keyword group.

The setup that worked

For all seven I used the same Maven skeleton. One pom.xml that I copied between projects, with a relocation for shading the Astroworld utility package so plugins don't conflict if you load multiple:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.5.0</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals><goal>shade</goal></goals>
      <configuration>
        <relocations>
          <relocation>
            <pattern>com.astroworld.util</pattern>
            <shadedPattern>com.astroworld.AstroSimpleAFK.shaded.util</shadedPattern>
          </relocation>
        </relocations>
      </configuration>
    </execution>
  </executions>
</plugin>

The relocation is the kind of detail that matters once you have more than two plugins from the same author. Without it, the moment two plugins ship the same utility class with different versions, one of them silently breaks.

Config patterns I kept reusing

After plugin 3 I noticed I was rewriting the same three things every time:

A config.yml migration on load. When you ship v1.0 and then v1.1 adds a new key, you don't want to crash because the user's old config doesn't have it. Standard pattern:

@Override
public void onEnable() {
    saveDefaultConfig();
    int version = getConfig().getInt("config-version", 1);
    if (version < CURRENT_VERSION) migrateConfig(version);
}

private void migrateConfig(int from) {
    if (from < 2) {
        getConfig().set("new-feature", true);  // sensible default
    }
    if (from < 3) {
        getConfig().set("another-feature", "default");
    }
    getConfig().set("config-version", CURRENT_VERSION);
    saveConfig();
}

It feels like overkill at v1.0 when there's only one version. It's not. The moment you ship v1.1 with a new feature, every user who copies the new JAR over the old one wants this to work without losing their existing config.

A Messages helper that pulls strings from messages.yml. Don't hardcode chat strings. Don't store them in config.yml. Put them in a separate file users can edit without touching settings.

public class Messages {
    private static FileConfiguration messages;

    public static String get(String key, String fallback) {
        return ChatColor.translateAlternateColorCodes('&',
            messages.getString(key, fallback));
    }
}

The fallback parameter is important. If a user is on the latest plugin with an old messages.yml, you want a sane default, not a missing string.

One LuckPerms hook helper. All five of the plugins that need permissions integration use the same pattern:

public String getGroup(Player p) {
    LuckPerms api = LuckPermsProvider.get();
    User user = api.getUserManager().getUser(p.getUniqueId());
    if (user == null) return "default";
    return user.getPrimaryGroup();
}

If LuckPerms isn't installed, this returns "default" for everyone. The plugin keeps working with one tier, which is what you want.

A bug I shipped, and what I learned

For AstroPlayerStats I shipped v1.0.0 with a synchronous SQLite write on every block-break event. On a busy server with one player digging through a tunnel with Efficiency V, that's around 25 writes per second. SQLite handles this if you don't fsync after every write, but my code called connection.commit() after each insert. So 25 fsyncs per second, on a single shared spinning disk.

The first user to install it ran /tps and saw 14 TPS. They came into Discord and asked if it was supposed to do that.

The fix took an hour: batch writes into a per-player queue, flush every 5 seconds or every 100 events whichever comes first, with one transaction per flush.

private final Map<UUID, Queue<StatEvent>> pending = new ConcurrentHashMap<>();

@EventHandler
public void onBlockBreak(BlockBreakEvent e) {
    pending.computeIfAbsent(e.getPlayer().getUniqueId(),
        k -> new ConcurrentLinkedQueue<>())
        .add(new StatEvent(StatType.BLOCK_BROKEN, 1));
}

// Scheduled task, async, every 5 seconds:
private void flush() {
    try (Connection conn = pool.getConnection()) {
        conn.setAutoCommit(false);
        for (var entry : pending.entrySet()) {
            // ... batched inserts
        }
        conn.commit();
    } catch (SQLException ex) {
        // log and keep events in queue for next flush
    }
}

TPS went back to 20. The lesson is one every Minecraft developer knows by lunchtime on their first plugin: never block the main thread, never call commit() in a hot path, and never trust the synchronous JDBC API to be fast enough.

What you should do if you build your own

A few things I wish someone had told me before plugin #1:

Start with a clean plugin.yml. Set api-version: '1.20' so the server doesn't print legacy warnings. Set load: STARTUP only if you actually need to register listeners that other plugins depend on. Skip softdepend for plugins that aren't required to function (PlaceholderAPI usually is softdepend, LuckPerms usually isn't unless you're a permissions plugin).

Don't shade Paper's API. I've seen plugins ship a 12 MB JAR because they shaded paper-api. The server already has it. Shading it makes your JAR huge and can break class loading in subtle ways.

Write README sections in this order: features, install, commands, permissions, config, compatibility. That's what server owners look for, in that order. Putting "About the developer" at the top is a tell.

Ship a sample config.yml with every option commented. Server owners read the config, not the plugin documentation. If your config has six keys and four of them don't say what they do, you've already lost half your installs.

Test on Paper, Spigot, and Purpur. They're API-compatible 99% of the time, that 1% will bite you. Tab-list manipulation in particular changed between Paper builds within the same Minecraft version twice in 2024.