Forem: AstroworldMC

I Built 7 Free Minecraft Plugins in a Weekend

AstroworldMC — Sat, 16 May 2026 16:56:00 +0000

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.

The code

All seven plugins, source + JARs, are at github.com/astroworld-mc, MIT licensed.

The server they were built for runs at astroworldmc.com. The data API I built alongside is at api.astroworldmc.com and is also open.

If you fork or improve any of them, I'd love to see what you change. The README of each repo points to the issue tracker.

Built by Astroworld. Plugins, API, and tools at github.com/astroworld-mc. Hosting that runs them well: Astroworld Hosting.

Auto-Indexing 30 Sites with IndexNow and Google Indexing API

AstroworldMC — Fri, 15 May 2026 16:56:00 +0000

The problem

I run a small constellation of sites — a main brand site, a few content-heavy reference databases for Minecraft (mobs, biomes, items, enchantments, structures), a hosting page, a status page, a few tool pages. 29 deployed sites total, plus one main domain. Every time I push new pages, Google takes a week to discover them through the sitemap, and Bing takes longer. For pages that target time-sensitive search terms, that's a real cost.

I wrote a small service called Indexing-Astroworld that solves two problems:

Detect new and changed URLs across all 30 sites every 6 hours
Submit them to IndexNow (Bing, Yandex, Naver, Seznam) and Google Indexing API the moment they exist

It runs on the same VPS as the rest of the stack. It's about 400 lines of TypeScript. This post is what I actually built and a few things I learned along the way.

IndexNow vs Google Indexing API

These are not the same thing. People mix them up constantly.

IndexNow is a simple HTTP POST protocol. You send a list of URLs to https://api.indexnow.org/indexnow and search engines that participate (Bing, Yandex, Naver, Seznam, Cloudflare-fronted versions) get notified. It's open. No auth, no quota that I've ever hit, no rate limit documented. The "key" is a random string you publish at https://yourdomain.com/{key}.txt so the search engine can verify you own the domain.

Google Indexing API is the opposite. It's authenticated with a Google Cloud service account, quota is 200 URL submissions per day per project, and Google's own docs say it's primarily intended for JobPosting and BroadcastEvent schema. They will index other URLs but rank them through normal channels. Useful, but limited.

Together they cover Bing, Yandex, Google, plus some Cloudflare workers that pick up IndexNow signals.

The architecture

┌────────────────────┐    every 6h    ┌────────────────────┐
│  systemd timer     │ ─────────────► │  diff worker       │
└────────────────────┘                │  - fetch sitemaps  │
                                      │  - compare to disk │
                                      │  - emit diff       │
                                      └─────────┬──────────┘
                                                │ new + changed URLs
                                                ▼
                                      ┌────────────────────┐
                                      │  submitter         │
                                      │  ┌──IndexNow ──┐   │
                                      │  └──Google API──┘  │
                                      └────────────────────┘

No queue, no database. The diff worker reads last-snapshot.json from disk, fetches every sitemap, computes the new and changed URL lists, then submits and writes the new snapshot back. If anything fails, the systemd timer fires again in 6 hours and tries again with the same comparison.

The sitemap discovery loop

const SITES = [
  "https://astroworldmc.com",
  "https://api.astroworldmc.com",
  "https://mobs.astroworldmc.com",
  // ...30 total
];

async function fetchSitemap(origin: string): Promise<string[]> {
  const url = `${origin}/sitemap.xml`;
  const res = await fetch(url, {
    headers: { "User-Agent": "AstroworldIndexer/1.0" },
    signal: AbortSignal.timeout(20_000),
  });
  if (!res.ok) {
    console.warn(`[indexer] ${origin} sitemap returned ${res.status}`);
    return [];
  }
  const xml = await res.text();
  return [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]);
}

A few notes from running this in production for a couple of months.

The AbortSignal.timeout is not optional. Without it, one slow origin (or, more often, one origin you forgot to renew DNS for) blocks the entire run. The default fetch timeout in Node 20 is effectively infinite. 20 seconds is plenty for a small sitemap.

Some sites return an index sitemap that points to per-section sitemaps. I added a second pass:

async function expandSitemap(origin: string): Promise<string[]> {
  const top = await fetchSitemap(origin);
  const isIndex = top.some((u) => u.includes("sitemap") && u.endsWith(".xml"));
  if (!isIndex) return top;

  const all: string[] = [];
  for (const childUrl of top) {
    const res = await fetch(childUrl, { signal: AbortSignal.timeout(20_000) });
    if (!res.ok) continue;
    const xml = await res.text();
    all.push(...[...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]));
  }
  return all;
}

You can do this concurrently with Promise.all if your sitemaps are big. Mine aren't, so the serial fetch is fine and easier to reason about.

The diff

type Snapshot = Record<string, { urls: Set<string>; etag?: string }>;

async function diff(prev: Snapshot, current: Snapshot) {
  const newUrls: string[] = [];
  const changedUrls: string[] = [];

  for (const [origin, { urls }] of Object.entries(current)) {
    const prevUrls = prev[origin]?.urls ?? new Set();
    for (const url of urls) {
      if (!prevUrls.has(url)) newUrls.push(url);
    }
  }

  // Changed: URLs whose lastmod differs. Easy if you parsed lastmod;
  // I skip this because most of my sitemaps don't carry stable lastmods.

  return { newUrls, changedUrls };
}

I deliberately do not detect "changed" URLs through content hashing. Fetching every URL on every site every 6 hours to compute a hash would be wasteful. If a page changes meaningfully, I update the sitemap's <lastmod> and re-submit through the same path. Most of the value is in catching genuinely new URLs anyway.

Submitting to IndexNow

const INDEXNOW_KEY = process.env.INDEXNOW_KEY!;

async function submitToIndexNow(host: string, urls: string[]) {
  const res = await fetch("https://api.indexnow.org/indexnow", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      host,
      key: INDEXNOW_KEY,
      keyLocation: `https://${host}/${INDEXNOW_KEY}.txt`,
      urlList: urls,
    }),
  });

  if (res.status === 202) {
    console.log(`[indexnow] ${host}: ${urls.length} accepted`);
    return { ok: true, count: urls.length };
  }
  console.warn(`[indexnow] ${host}: ${res.status} — ${await res.text()}`);
  return { ok: false };
}

You submit one batch per host. The protocol returns 202 Accepted and that's the only response you should expect for a healthy run. 200 means the call worked but no URLs were processed (often this is a key mismatch). 429 means you hit a rate limit that isn't documented but seems to land around 10,000 URLs per minute.

The keyLocation is mandatory. Without it the protocol can't verify you own the host. The file at that path needs to literally contain the key string, nothing else, served as text/plain.

Submitting to Google Indexing API

The Google side is more involved because of OAuth.

import { google } from "googleapis";

const auth = new google.auth.GoogleAuth({
  keyFile: "/etc/astroworld/google-indexing.json",
  scopes: ["https://www.googleapis.com/auth/indexing"],
});

async function submitToGoogle(url: string, type: "URL_UPDATED" | "URL_DELETED") {
  const client = await auth.getClient();
  const indexing = google.indexing({ version: "v3", auth: client });
  await indexing.urlNotifications.publish({
    requestBody: { url, type },
  });
}

Two things to flag.

The service account needs Webmaster ownership. You add the service account's email as a delegated owner inside Google Search Console for each property. Without this you get 403 Permission denied. The error message helpfully suggests you visit a URL that doesn't address the issue.

Daily quota is 200 URLs. If your first run has 2,000 new URLs you will only get the first 200 indexed via this path. That's fine — the rest go through IndexNow and the regular Googlebot crawl. The quota resets at midnight Pacific time.

I wrap it like this:

const GOOGLE_QUOTA = 200;

async function submitGoogleBatch(urls: string[]) {
  let used = 0;
  for (const url of urls.slice(0, GOOGLE_QUOTA)) {
    try {
      await submitToGoogle(url, "URL_UPDATED");
      used++;
    } catch (err: any) {
      if (err.code === 429) {
        console.warn("[google] quota exhausted");
        break;
      }
      console.warn(`[google] ${url}: ${err.message}`);
    }
  }
  console.log(`[google] ${used}/${urls.length} submitted`);
  return used;
}

I do not retry. If a single URL fails I'd rather skip it and move on — the goal is to get most URLs indexed quickly, not every URL perfectly.

Real numbers

On the first run after the worker shipped:

2,434 URLs total discovered across 30 sites
1,730 URLs net-new (the others were already in the previous snapshot — first run had a previous snapshot of zero, so this is "first time the system saw them")
200 went through Google Indexing API in the first 60 seconds
The remaining 1,530 went through IndexNow
Bing started showing those URLs in their index ~36 hours later
Google picked up the long tail over the next week

Per 6-hour run since then, typically 10-40 new URLs (new mob pages, new guide articles, new "where to find" landing pages).

What I'd build differently

Persist the snapshot in a tiny SQLite file, not a JSON blob. With JSON I rewrite the whole thing on every run. With SQLite I'd do incremental updates and survive a crash mid-write. Not a real problem at my scale but it's the kind of thing that bites later.

Submit changed URLs (with lastmod parsing), not only new URLs. Right now if you edit a page without changing the URL, the indexer doesn't notice. I want to add lastmod diffing.

Health endpoint that reports drift. If a sitemap suddenly drops 90% of its URLs, that's almost certainly a deploy bug, not a real drop. The indexer should refuse to submit a delete-everything event and page me instead.

Try it

The full service is at github.com/astroworld-mc (the indexing worker will be opened-up shortly). The API it indexes lives at api.astroworldmc.com and you can poke at it without an account.

If you run a multi-site stack and Google takes a week to discover your new pages, you don't need a CDN, you need IndexNow. It's two endpoints and a key file.

Built by Astroworld. All the supporting open-source repos live at github.com/astroworld-mc. If you want server hosting that handles this kind of small-but-busy stack well, Astroworld Hosting.

Building a Free Public Minecraft Data API

AstroworldMC — Thu, 14 May 2026 16:52:58 +0000

Why I built it

For one of our Minecraft community projects I needed structured data: HP values, drop tables, spawn biomes, biome temperatures, enchantment max levels, structure rarities. The data exists, but if you scrape it from the wiki you spend a week cleaning it, and Mojang's own APIs only cover player profiles and skin endpoints.

The plan was simple. Build a small JSON API that exposes everything (mobs, biomes, items, enchantments, structures, commands, versions, achievements, trades), keep it free, no signup, CORS open, and host it on a single VPS.

That was a weekend project. It now serves around 1,500 records under api.astroworldmc.com, open source on github.com/astroworld-mc.

This post is the actual decisions I made, with the code that's running in production right now, and the things I'd do differently if I started again.

Stack

Next.js 15 App Router
TypeScript
No database. Data lives in flat .ts files
One small in-memory rate limiter
Nginx in front for TLS + a clean /v1/... rewrite
Runs on a single next start process on port 3040

That's it. No Redis, no Postgres, no Kubernetes, no edge functions. The whole thing fits in about 250 MB resident memory and the cold-start build takes 14 seconds.

Decision 1: TypeScript arrays, not a database

I knew this was going to be controversial so I want to address it first.

Every record is a TypeScript const, like this:

// data/mobs.ts (excerpt)
export const MOBS: Mob[] = [
  {
    name: "Creeper",
    id: "creeper",
    type: "hostile",
    hp: 20,
    damage: { easy: 0, normal: 24, hard: 49 },
    spawnBiomes: ["Plains", "Forest", "..."],
    drops: [
      { item: "Gunpowder", count: { min: 0, max: 2 }, chance: 100 },
    ],
    behavior: "Silently approaches players and detonates after a 1.5s fuse.",
    // ...
  },
  // ~184 more
];

Three reasons I went with this over a database:

1. The data does not change at request time. A Creeper has 20 HP. It had 20 HP last year. It will have 20 HP next year. The only writes happen when Mojang patches the game, which is roughly four times a year. So writing performance is irrelevant and durability is git.

2. Git diffs are readable. When Mojang nerfs a mob in 1.21.4 I can see the change as a normal pull request. I can revert with git revert. I can blame a line. I cannot do any of that with a mobs table that someone updated through pgAdmin.

3. TypeScript checks the shape. Every record is type-checked at build time. If I forget a field I get a red squiggle in VS Code, not a 500 at runtime. With a database I would have to write a Zod schema and validate on the way in.

The cost: the whole dataset is loaded into memory at start. For 1,500 records of mostly short strings this is around 4 MB, so it does not matter. If the dataset hits 100,000 records I will re-evaluate.

Decision 2: One route handler per resource

Every endpoint looks like this:

// app/api/v1/mobs/route.ts
import { NextRequest, NextResponse } from "next/server";
import { MOBS } from "@/data/mobs";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type",
};

export async function GET(req: NextRequest) {
  const { searchParams } = new URL(req.url);
  const search = searchParams.get("search");
  const type = searchParams.get("type");

  let results = [...MOBS];
  if (search) {
    results = results.filter(m =>
      m.name.toLowerCase().includes(search.toLowerCase())
    );
  }
  if (type) {
    results = results.filter(m => m.type === type.toLowerCase());
  }

  const pretty = searchParams.get("pretty") === "true";
  const body = { success: true, count: results.length, data: results };

  return new NextResponse(JSON.stringify(body, null, pretty ? 2 : 0), {
    headers: { "Content-Type": "application/json", ...corsHeaders },
  });
}

export async function OPTIONS() {
  return new NextResponse(null, { status: 204, headers: corsHeaders });
}

I considered a generic /api/v1/[resource]/route.ts with a switch on the slug. I'm glad I did not. The current setup means every endpoint can have its own filter set, its own type signature, and its own validation. The duplication is around 6 lines per file and that's a worthwhile trade for the readability.

?pretty=true is a small thing I always add. Nine times out of ten when someone is poking at the API for the first time they paste the URL into a browser, and pretty-printed JSON is friendly. The server cost is negligible because JSON.stringify is the same work either way.

Decision 3: CORS open by default

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type",
};

* is fine here. The data is public, there are no cookies, no auth, no PII. Someone building a Discord bot or a static site needs to call it from the browser without a CORS proxy. If you set this to a specific origin you cripple the API's main use case.

The trade-off you accept with *: you cannot ever attach auth without changing the policy. That's a problem for future-me. Future-me can deal with it.

Decision 4: In-memory rate limiting

Public, free API with no signup means someone will hammer it eventually. The middleware is short:

// middleware.ts
const rateMap = new Map<string, { count: number; resetAt: number }>();
const WINDOW_MS = 60_000;
const MAX_REQUESTS = 100;

export function middleware(req: NextRequest) {
  if (!req.nextUrl.pathname.startsWith("/api/")) {
    return NextResponse.next();
  }

  const ip = getClientIp(req);
  const now = Date.now();
  const entry = rateMap.get(ip);

  if (!entry || now > entry.resetAt) {
    rateMap.set(ip, { count: 1, resetAt: now + WINDOW_MS });
  } else {
    entry.count++;
  }

  const current = rateMap.get(ip)!;
  const remaining = Math.max(0, MAX_REQUESTS - current.count);

  if (current.count > MAX_REQUESTS) {
    return new NextResponse(
      JSON.stringify({
        success: false,
        error: "Rate limit exceeded. Max 100 requests per minute.",
      }),
      { status: 429, headers: { /* ratelimit headers + cors */ } }
    );
  }

  const response = NextResponse.next();
  response.headers.set("X-RateLimit-Limit", String(MAX_REQUESTS));
  response.headers.set("X-RateLimit-Remaining", String(remaining));
  return response;
}

Two things to flag.

The Map never gets cleaned up. Each unique IP gets an entry. After a year of traffic that Map could grow to millions of keys. In practice the process gets restarted every few weeks for deployments and the Map resets, but if you copy this verbatim for a long-running process you want a periodic sweep that drops expired entries. Add this:

setInterval(() => {
  const now = Date.now();
  for (const [ip, entry] of rateMap) {
    if (now > entry.resetAt) rateMap.delete(ip);
  }
}, 5 * 60_000);

It does not work across multiple instances. If you scale to two processes behind a load balancer, each has its own Map, and a client can do 100 requests per minute against each. For a single-VPS hobby API this is fine. For anything bigger you move to Redis or upstash.

The header names match the IETF draft (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Clients that already speak that convention work without changes.

Decision 5: Nginx for TLS, not Next.js

next start listens on 0.0.0.0:3040. Nginx terminates TLS and reverse-proxies to it:

location /v1/ {
  rewrite ^/v1/(.*) /api/v1/$1 break;
  proxy_pass http://127.0.0.1:3040;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Two notes.

The rewrite lets users hit https://api.astroworldmc.com/v1/mobs (clean) and have Nginx forward to /api/v1/mobs (which is where Next puts route handlers). I didn't want users to type /api/v1/ because nothing about the implementation should leak through the URL.

X-Real-IP is what the rate limiter reads. Without it, the rate limiter sees Nginx's loopback address and rate-limits the whole world together. Easy mistake.

What I would do differently

Add HEAD support. Some clients probe with HEAD before GET. Next.js route handlers don't auto-derive HEAD from GET, so right now those probes get 405. Not a real bug, but it's noisy in the logs.

Stream JSON for large responses. Returning all 184 mobs in one response is fine, but /v1/structures with all generation rules is around 200 KB. For dashboard consumers that's noticeable. Streaming would help.

Document the schema. Right now there's a README and the TypeScript types. There's no OpenAPI spec. I keep meaning to generate one from the types. If you have a good TS-to-OpenAPI generator, drop a comment.

Add an etag. The data only changes a few times a year. An ETag based on the build hash would let clients cache aggressively with If-None-Match.

Use it, fork it

The whole repo is at github.com/astroworld-mc, MIT licensed. The API itself is live at api.astroworldmc.com, try /v1/mobs?search=creeper or /v1/biomes?type=overworld.

If you build something on top of it (a Discord bot, a Twitch overlay, a wiki generator) I would love to see it. The Astroworld project lives at astroworldmc.com and started as a small Minecraft server. The API is the first thing we open-sourced from it.

Built by Astroworld. The API and 7 supporting plugins are on GitHub. Server hosting that runs this kind of project well: Astroworld Hosting.