StackNest Documentation

Everything you need to get better generations, cleaner outputs, and a smoother path from prompt to deployed plugin.

What is StackNest?

StackNest is an AI development tool for Minecraft server plugins, Fabric/Forge/NeoForge mods, and related server workflows. You describe what you want in plain English — for example “a Fabric mod that adds a /heal command and a glowing apple item” or “a plugin that rewards players when they vote” — and StackNest generates the code, metadata, and validation feedback.

You do not need to be a Java expert to get started. The goal is to shorten the path from idea to working plugin or mod, then give you enough tooling to refine, validate, and deploy with confidence.

Discord bot hosting

StackNest also includes hosted Discord bots at /bots. You can generate a bot with AI or upload your own Python .py file (or a .zip archive), then deploy and manage it in one place.

• Upload your own bot code from the Discord Bots page with the Upload .py or .zip Bot File action, or drag and drop the file directly.
• Deploy with your Discord token, then use start, stop, restart, and logs controls in the same dashboard.
• Access depends on plan limits.

Generating mods with AI

In addition to server plugins, StackNest can generate Fabric, Forge, and NeoForge mods from a single prompt. Mod generation runs through the same AI pipeline as plugin generation, but produces mod-specific source files instead of a compiled server plugin.

What you get from a mod generation:

• A main Java class implementing the correct mod entry point (ModInitializer for Fabric, @Mod class for Forge/NeoForge)
• The mod metadata file — fabric.mod.json for Fabric, mods.toml for Forge/NeoForge
• A build.gradle.kts Gradle build file
• A server-side Gradle compile pass — on success, a ready-to-install .jar download link
• Inline comments explaining how to wire up the generated features

Fabric, Forge & NeoForge

Your first mod

1. Switch to Mods mode In the generator at /app, click the Mods pill at the top of the composer. The control strip will change to show mod options.
2. Choose your loader and MC version Select Fabric, Forge, or NeoForge and pick the Minecraft version you are targeting. Give your mod a name.
3. Select feature chips (optional) Toggle chips like Custom items, Commands, Event listeners, or Config file to add those patterns to your generation.
4. Describe your mod Write what the mod should do, e.g. “A Fabric 1.21 mod that adds a /heal command and a custom glowing apple item.” The more detail, the better the output.
5. Download your compiled .jar When the build succeeds, click the Download .jar button and drop the file into your server’s mods/ folder. If compilation did not succeed, the full source files are still available so you can build locally with ./gradlew build.

Skript generation

Skript is a scripting plugin for Paper that lets you add game logic in plain-English syntax — no Java compilation needed. StackNest generates complete .sk script files using the Skript 2.x rule set.

How to generate a Skript

1. Click the Skript pill On the generator at /app, click Skript in the mode pills row. The composer strips down to just a text box — no loader or version selector needed.
2. Describe what you want Write what the script should do, e.g. “A /sethome and /home command that saves each player’s home location and teleports them back to it.”
3. Download and install Save the generated .sk file into your server’s plugins/Skript/scripts/ folder. Run /sk reload all or restart the server.

What StackNest enforces for Skript

• Indentation-based scope — no braces, no semicolons
• Correct event names: on join: not on player join:
• Variables: {global} for persistent, {_local} for temporary, {list::*} for lists
• String interpolation with %expr% inside "..."
• Stores player UUIDs, not player objects, in long-lived variables
• No Java syntax leaking in (no ;, no {} blocks, no import)

Datapack generation

Vanilla datapacks let you modify game behaviour without a plugin or modloader — using only JSON files, .mcfunction scripts, and folder conventions that Minecraft reads natively.

StackNest generates a complete datapack file tree for MC 1.21+ and labels each file with its intended path, so you know exactly where to place it.

How to generate a datapack

1. Click the Datapacks pill On the generator at /app, click Datapacks. A MC version dropdown appears — pick the version you are targeting.
2. Describe your datapack Explain what it should do: “Give players the Speed II effect when they eat a golden carrot. Remove it after 30 seconds.”
3. Install the output Create a folder inside your world’s datapacks/ directory with the namespace name. Drop the generated files into the correct sub-paths (each file in the output starts with a comment showing its path). Run /datapack enable "file/<name>" and /reload.

What StackNest generates for datapacks

• pack.mcmeta — with the correct pack_format for the Minecraft version you asked for, so you do not need to look it up manually.
• data/<namespace>/functions/ — .mcfunction files for tick, load, and any custom logic
• Tick & load function tags in data/minecraft/tags/function/
• Advancements, recipes, loot tables, and predicates in JSON
• Scoreboard initialisation in the load function

Your first plugin

1. Create a free account Go to /app and sign up with your email. Verify your email — you'll get a confirmation link.
2. Describe your plugin Type what you want in the prompt box. Be specific — the more detail you give, the better the result. See Writing better prompts.
3. Wait for generation Click Generate. StackNest writes your plugin, validates it, and attempts automatic corrections when needed. This usually takes 15–60 seconds, but larger plugins can take longer.
4. Download your JAR Once generated, click Download JAR. Drop the .jar file into your server's plugins/ folder and restart.

Writing better prompts

The quality of your plugin depends heavily on how clearly you describe it. Here are the key things to include:

• What triggers the plugin — a command, an event (player joins, breaks a block, dies), a timer
• What it does — the specific action or behaviour
• Who it affects — all players, specific permissions, ops only
• Any configuration — messages, cooldowns, limits
• Any dependencies — Vault, LuckPerms, PlaceholderAPI, databases, or other required plugins

Prompt template

Use this structure when you want more reliable results:

Build a Paper 26.1 plugin.

Main features:
- [feature 1]
- [feature 2]

Commands:
- /example

Permissions:
- example.use for regular players
- example.admin for admins

Config:
- message text should be configurable
- cooldown should default to 30 seconds

Storage / integrations:
- use YAML / SQLite / Vault / LuckPerms

Notes:
- make this Folia-compatible if needed
- keep messages formatted with Adventure components

Prompt examples

Platform overview

Minecraft server software comes in many flavours. Choosing the right one affects what features your plugin can use.

Which platform should I choose?

How generation works

When you hit Generate, StackNest goes through several steps automatically:

1. Your prompt is sent to the AI — it writes Java code and descriptor files based on what you described.
2. For paid plans: Smart Assembly — before the main generation pass, a quick AI analysis step identifies which advanced features your plugin needs (Vault, SQLite, GUI click handlers, Folia scheduler, PDC storage, repeating tasks, etc.). Pre-validated Java code blocks for those features are injected directly into the prompt. This significantly reduces the chance of API mistakes, because boilerplate comes from tested templates rather than being generated from scratch.
3. For plugins: the code is compiled — the plugin is compiled against the real PaperMC API and any errors are shown.
4. For plugins: automatic fixing — if the code has issues, StackNest retries with targeted corrections before returning the result.
5. For mods: Gradle compile + .jar — StackNest runs a server-side Gradle build (Fabric Loom / ForgeGradle / NeoGradle). On success you get a downloadable .jar. If the build has errors, StackNest retries with corrections. The full source files are always included.
6. For Skript: .sk file output — a complete .sk script ready to drop into plugins/Skript/scripts/. No compilation step.
7. For datapacks: full file tree — pack.mcmeta, .mcfunction files, JSON tags, advancements, recipes, and loot tables. Each file is labelled with its install path.
8. You get the output — the code, any warnings, and a download button for the compiled JAR (plugins and successfully-compiled mods) or source files (Skript, datapacks).

Architecture patterns the AI is guided to use

For complex plugins the AI follows a set of production-grade patterns, not just syntactically correct Java:

• Layered manager classes — a top-level DatabaseManager, CacheManager, and service layer instead of logic in the main plugin class.
• Async-safe player data loading — a ConcurrentHashMap<UUID, CompletableFuture<PlayerData>> dedup map so the database is hit exactly once per UUID even under concurrent join events.
• Bounded write queues — a LinkedBlockingQueue with a configurable size cap and inline fallback, flushed before shutdown.
• Config-driven backpressure — a Semaphore sized to availableProcessors() * 2 limits concurrent database operations so threads are not exhausted under load.
• Stale-task guards — async callbacks check both plugin.isEnabled() and a System.nanoTime() instance ID so they silently drop work if the plugin was reloaded mid-flight.
• Retry jitter — failed external API calls back off with Math.random() * baseDelay to prevent thundering-herd retry storms.
• Copy-on-write snapshots — mutable PlayerData is snapshotted on the main thread before being handed to async writers to prevent torn multi-field reads.

Validation & errors

StackNest validates your plugin at every stage before returning the result:

• Java compilation — the code is compiled against the real Paper 26.1 API using Java 25. Compiler errors are captured and fed back into the auto-heal loop.
• plugin.yml check — all required fields are verified: name, version, main, and api-version. Missing or malformed entries are caught before the JAR is packaged.
• Static analysis — catches unsafe and broken patterns before the code ever reaches a server:
  • Main-thread violations — reading or writing world state from an async callback
  • Deprecated API use — removed or legacy Bukkit calls that break on Paper 1.17+
  • Thread.sleep() in async tasks — blocks the thread pool slot; replaced with runTaskLaterAsynchronously
  • Raw NMS access — internal Minecraft internals that break on every version bump
  • Unbounded collections and missing ConcurrentHashMap on shared state
  • Stale async callbacks after plugin reload (isEnabled() checks)
• Quality review — no truncated methods, no empty catch blocks, no placeholder comments left in the output.

If warnings appear after generation they are usually minor (like an unused import) and the plugin will still work. Errors shown in red mean compilation failed — try regenerating with a more specific prompt, or describe what went wrong and the auto-heal loop will attempt a targeted fix.

Downloading your JAR

After a successful generation, click Download JAR. You'll get a .jar file ready to install:

1. Stop your server (or let it run — hot-loading is possible but not recommended).
2. Drop the .jar into your server's /plugins folder.
3. Start (or restart) the server.
4. The plugin loads automatically. Check your console for any startup errors.

Runtime plugin testing

Instead of downloading a JAR and deploying it to your own server, you can ask StackNest to boot a real Paper 26.1 server instance, load your plugin, and return a structured diagnostic report — all within the browser, in under 60 seconds. You can test both StackNest-generated plugins and plugins you have built yourself — just upload the JAR directly.

How to use it

1. Generate a plugin as normal in the editor, or upload your own .jar using the Upload & Test JAR button in the action bar.
2. For StackNest-generated plugins: click Test on Server in the action bar once generation succeeds (Starter and above only).
3. A results panel slides open and streams the test output. It takes roughly 30–60 seconds.
4. Review the stat tiles (load time, warnings, errors) and the StackNest Insights section for AI-powered fix hints.
5. Expand Full server log for the raw Paper output if you need to dig deeper.

Plan limits

What the report includes

• Load status — whether the plugin enabled successfully.
• Errors & warnings — counts extracted directly from the server log.
• Stack traces — any Java exceptions printed during startup or the first tick.
• StackNest Insights — up to 25 AI-powered hints matched against common plugin issues (missing dependencies, deprecated API calls, unsafe async operations, and more).
• Full server log — the complete Paper console output, expandable on demand.

Gallery

The Gallery is a community library of plugins that users have uploaded for others to use freely.

• Browsing — anyone can browse and download plugins from the gallery, no account needed.
• Uploading — you need a verified account. Upload a .jar or .zip containing your plugin (it must have a valid plugin.yml inside).
• Tagging — tag your upload with the platforms it supports (Paper, Spigot, etc.) so others can filter by platform.

Recommended workflow

1. Start narrow — generate one core feature first instead of a giant all-in-one plugin.
2. Test the basics — check commands, permissions, and startup logs on a local Paper test server.
3. Iterate in follow-ups — add one feature at a time so the AI has a clear next step.
4. Use the editor and log analyser — they are the fastest path when a plugin almost works but still needs cleanup.

Plans & limits

See the pricing page for full details and to upgrade.

API access Studio

Studio subscribers can generate plugins and mods over HTTP — no browser required. Pipe StackNest into CI/CD pipelines, Discord bots, server panels, or your own tooling.

Getting your API key

1. Log in and open Profile → API Access.
2. Click Generate key. The full key is shown once only — copy it immediately and store it securely.
3. Use the key in an Authorization: Bearer header on every request.

Authentication

Pass your key as a standard Bearer token. The legacy X-API-Key header is also accepted for backwards compatibility.

# Preferred
Authorization: Bearer sn_<your-key>

# Also accepted
X-API-Key: sn_<your-key>

Versioned base path

All endpoints are available under both /api/ and /api/v1/. The versioned path is recommended for new integrations — it will remain stable as the API evolves.

Endpoints

GET /api/v1/user/me

Returns your identity, plan, and monthly quota. Accepts both browser session cookies and Bearer token.

curl https://stacknests.com/api/v1/user/me \
     -H "Authorization: Bearer sn_<your-key>"

{
  "username":        "YourStudio",
  "email":           "you@example.com",
  "plan":            "studio",
  "gens_used":       14,
  "gens_remaining":  286,
  "gens_limit":      300,
  "days_until_reset": 18
}

POST /api/v1/generate

Generate a plugin (Paper, Spigot, Folia, Velocity, Skript, datapack). Each successful call counts as one generation against your monthly quota. Expect 15–120 seconds — set your HTTP client timeout accordingly and do not retry on a live request.

For Fabric, Forge, and NeoForge mods use the SSE endpoint POST /api/generate-mod-progress — it streams live progress and returns a jar_download_url in the final done event.

curl https://stacknests.com/api/v1/generate \
     -H "Authorization: Bearer sn_<your-key>" \
     -H "Content-Type: application/json" \
     -d '{"prompt":"A Paper 26.1 plugin that adds a /heal command","platform":"paper"}'

The response includes request_id, code (Java source), plugin_name, compile_ok, gallery_id, and any warnings / errors. To download the compiled JAR, pass the returned code to POST /api/jar.

{
  "request_id":      "gen_3f8a1c",
  "success":         true,
  "code":            "...",
  "plugin_name":     "HealPlugin",
  "compile_ok":      true,
  "yml_ok":          true,
  "attempts":        2,
  "elapsed_seconds": 18.4,
  "gallery_id":      391,
  "warnings":        [],
  "errors":          []
}

POST /api/jar

Compile plugin source (from a /api/v1/generate response) into a ready-to-deploy .jar. Returns a binary file download.

curl https://stacknests.com/api/jar \
     -H "Authorization: Bearer sn_<your-key>" \
     -H "Content-Type: application/json" \
     -d '{"code":"<code from /api/v1/generate>","plugin_name":"HealPlugin"}' \
     --output HealPlugin.jar

GET /api/mod-jar/<token>

Download a compiled mod JAR. The token comes from the jar_download_url field in the done event of an /api/generate-mod-progress SSE stream. Tokens are valid for 2 hours.

curl "https://stacknests.com/api/mod-jar/<token>" \
     -H "Authorization: Bearer sn_<your-key>" \
     --output my-mod-1.0.jar

Errors

All error responses follow a consistent shape. Use error for display and detail (when present) for logging.

// 401 — bad or missing key
{ "error": "Invalid API key" }

// 429 — quota exhausted
{ "error": "Monthly generation limit reached (300/month). Resets in 18 days.",
  "usage": { ... }, "upgrade_url": "/pricing" }

// 503 — AI backend temporarily unavailable
{ "error": "AI backend is unreachable right now. Please try again in 30 seconds.",
  "detail": "ConnectionError: ..." }

Retry on 5xx with exponential backoff. Do not retry 4xx — those indicate a client-side issue that a retry will not fix.

Rate limits

Studio API keys share the same monthly generation quota as browser use. There is no separate per-minute rate limit for Studio keys. If you need higher throughput, contact support.

Python quick-start

import os, time, requests

KEY  = os.environ["STACKNEST_API_KEY"]
BASE = "https://stacknests.com"

def generate(prompt, platform="paper", retries=3):
    for attempt in range(retries):
        try:
            r = requests.post(
                f"{BASE}/api/v1/generate",
                headers={"Authorization": f"Bearer {KEY}"},
                json={"prompt": prompt, "platform": platform},
                timeout=150,  # generation can take up to 120s
            )
            if r.status_code < 500:
                r.raise_for_status()
                return r.json()
            # 5xx — back off and retry
            time.sleep(2 ** attempt)
        except requests.exceptions.Timeout:
            if attempt == retries - 1:
                raise
            time.sleep(2 ** attempt)
    raise RuntimeError("Generation failed after retries")

def download_jar(code, plugin_name, out_path):
    r = requests.post(
        f"{BASE}/api/jar",
        headers={"Authorization": f"Bearer {KEY}"},
        json={"code": code, "plugin_name": plugin_name},
        timeout=60,
    )
    r.raise_for_status()
    with open(out_path, "wb") as f:
        f.write(r.content)

result = generate("Paper 26.1 plugin: /heal command with a 30-second cooldown")
print(result["request_id"], result["plugin_name"], "compile_ok:", result["compile_ok"])

if result["compile_ok"]:
    download_jar(result["code"], result["plugin_name"], f"{result['plugin_name']}.jar")
    print(f"JAR saved → {result['plugin_name']}.jar")

Key management & security

• Keys are hashed with SHA-256. StackNest never stores the raw key.
• Rotate: Profile → API Access → Rotate key — old key invalidated instantly, new key shown once.
• Revoke: Profile → API Access → Revoke — permanently deletes the key with no recovery.
• Downgrading your plan below Studio automatically revokes the key.
• API calls consume monthly generations at the same rate as browser generations.

Common issues

My plugin generated but doesn't work on the server

Check your server console for error messages when the plugin loads. Common causes:

• Wrong server version — make sure your prompt mentioned the Minecraft version (e.g. "Paper 26.1").
• Missing dependency — if the plugin requires another plugin (like Vault or LuckPerms), make sure it's installed first.
• Folia compatibility — if you're on Folia, regenerate with "make this Folia-compatible" in your prompt.

Generation is taking a long time

Complex plugins can take up to 90 seconds. Mod generation may also take 30–60 seconds. If the page shows a spinner, it’s still working — don’t reload. If it times out, try again with a slightly simpler prompt and build up from there.

I get a compilation error in the output

This happens occasionally with very complex or unusual requests. Try:

• Regenerating with the same prompt (the AI might get it right on the next attempt).
• Simplifying your prompt slightly, then adding complexity in a follow-up generation.
• Being more specific about the Minecraft version and API you're targeting.

The plugin has "StackNest" as the author — can I change it?

On the free plan, authors: [StackNest] is added to your plugin.yml automatically. You can edit the file manually to change it, or upgrade to Pro to remove this entirely.

I’ve hit my monthly limit

Free accounts get 3 plugin/mod generations per month. If you need more headroom, move to Starter, Pro, or Studio depending on how often you generate and whether you need premium tooling.

Paper 26.x & Java 25

Paper 26.1 is a major release that changes how Paper is versioned and built. Instead of the old 1.x-R0.1-SNAPSHOT Maven scheme, Paper now uses its own version numbers like 26.1.2.build.62-stable. StackNest tracks the latest stable build automatically — you do not need to do anything.

Key differences from Paper 1.x

• Java 25 required — Paper 26.1 is compiled for Java 25. StackNest's compilation pipeline uses Java 25 automatically when targeting 26.1.
• Brigadier included on the compile classpath — the com.mojang:brigadier library is now an explicit compile dependency. You can use Brigadier commands without wrapping them in reflection.
• Command registration changed — use getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> { ... }). There is no class called CommandRegistrationEvent — that name does not exist in the API.
• New Paper-native API surface — many Bukkit-compatibility shims have been removed or deprecated. Use Paper's own APIs directly.

Brigadier & command errors

If you see errors like package com.mojang.brigadier.command does not exist or cannot find symbol … CommandRegistrationEvent, the causes are:

• com.mojang.brigadier.command — this package does not exist. The correct packages are com.mojang.brigadier and com.mojang.brigadier.context. Use com.mojang.brigadier.Command, not com.mojang.brigadier.command.Command.
• CommandRegistrationEvent — this class does not exist in Paper's API. Register commands via the lifecycle manager instead:

// Paper 26.1 command registration
@Override
public void onEnable() {
    getLifecycleManager().registerEventHandler(
        LifecycleEvents.COMMANDS,
        event -> {
            Commands cmds = event.registrar();
            cmds.register(
                Commands.literal("mycommand")
                    .executes(ctx -> {
                        ctx.getSource().getSender().sendMessage("Hello!");
                        return Command.SINGLE_SUCCESS;
                    })
                    .build()
            );
        }
    );
}

Service availability

StackNest uses AI services to generate plugins. Occasionally these services may be slower or temporarily unavailable during periods of high demand.

Pro users get priority queue access, meaning their requests are processed before free-tier requests during high-traffic periods.