Spigot / Paper Plugin Installation

This guide covers Spigot, Paper, Folia, and Purpur. The plugin is the same across all four.

Requirements

Requirement	Version	Details
Minecraft	1.8 through 1.21.x & 26.x	Java Edition & Bedrock (via GeyserMC)
Bedrock Edition	Supported via GeyserMC / Floodgate	Floodgate prefixes (., *, -, spaces) & gamertags up to 36 chars
Java	Match your server's requirement	Java 17 for 1.20.4, Java 21 for 1.20.5–1.21.11, Java 25 for 26.x; plugin bytecode targets Java 8
Server software	Spigot, Paper, Folia, or Purpur	Any one of them

Install

1. Download craftyai-spigot-1.4.1.jar from the 1.4.1 release.
2. Drop it into your server's plugins/ folder.
3. Start the server.

CraftyAI v1.3.0+ auto-saves the API key to your config on first start — no manual copying needed. Just start the server and the plugin handles everything.

For a manual key, set server.secret in plugins/CraftyAI/config.yml, then run /crafty reload. Keep that file private; avoid pasting keys into public chat.

That's it. Players can start talking to CraftyAI in chat.

What's in config.yml

The plugin generates a default config on first run. The fields that matter:

server:
  secret: "your-api-key"

ai:
  # What the AI is called in chat
  name: "Crafty"

  # Names players can use to address the AI
  aliases:
    - crafty
    - craftyai
    - ai
    - helper

  # Set to true to let the AI change time, weather, etc.
  enable_actions: true

  # Set to true to let the AI scan nearby blocks when asked
  allow_block_scanning: true

You probably won't need to change any of this. The defaults work for most servers.

Commands

Command	What it does
/crafty	Show plugin info
/crafty status	Check connection
/crafty reload	Reload config (admin only)
/crafty learn Q | A	Teach the AI (admin only)
/crafty ask <question>	Ask AI privately
/crafty scan	Scan nearby area
/crafty confirm	Confirm a destructive action
/crafty tasks	List your local scheduled tasks
/crafty tasks cancel <id>	Cancel a local task
/crafty cancel	Cancel your pending confirmation and local tasks
/crafty pro help	Show Pro key instructions
/crafty pro status	Show your current tier
/crafty pro redeem <key>	Redeem a Pro key
/crafty memory	View your stored memories
/crafty forget [n]	Forget a specific memory or all
/crafty privacy <on|off>	Toggle server-wide RAG memory opt-out (admin only)
/crafty mode <local|cloud>	Toggle between cloud and forced local offline mode (admin only)
/crafty prompt view	View your custom prompt (Pro only)
/crafty prompt set <text>	Set a custom AI prompt (Pro only)
/crafty prompt reset	Reset to default prompt (Pro only)
/crafty apikey	View or auto-mint API key
/crafty apikey rotate	Rotate existing API key
/crafty link	Get a code to link this server to your Discord

Permissions

The default permissions are designed so most servers don't need a permissions plugin. OPs get everything. Standard players get only crafty.chat, which lets them talk to the AI but not trigger actions like time changes.

If you want to grant actions to specific players, install LuckPerms and add crafty.actions.

GeyserMC / Bedrock support

CraftyAI works with Bedrock players through GeyserMC and Floodgate. Place the CraftyAI plugin JAR in your plugins/ folder alongside GeyserMC. Floodgate automatically appends a prefix (such as .) to Bedrock player names, and CraftyAI handles those correctly for chat, scanning, and actions. No additional configuration needed.

Config migration

When you update CraftyAI, your config is automatically migrated to the latest version. Your existing settings are preserved. A backup of the pre-migration config is saved as config.yml.bak in the plugin folder.

Folia note

Folia splits the server into multiple threads and regions. Use the Java version required by your Folia build; Java 17 is not sufficient for every version. CraftyAI uses separate global, region and entity scheduling paths. See the release's verification notes for the Folia versions and behavior actually tested.

Subscriptions

See Tiers & Subscriptions for the available tiers, Discord moderator request process and redemption instructions.

Help

If something doesn't work, check Common Issues or ask on Discord.