# CraftyAI - Comprehensive Documentation Corpus for AI Models

> **Publisher:** DemonZ Development  
> **Official Portal:** https://craftyai.pages.dev  
> **AI Manifest:** https://craftyai.pages.dev/ai.xml  
> **Format:** LLM Full Ingestion Reference (llms-full.txt)

---

# Table of Contents
1. Introduction & Architecture Overview
2. Getting Your API Key
3. Installation: Spigot & Paper Plugin
4. Installation: Fabric, Forge & NeoForge Mod
5. Server Administrator Guide
6. Natural Chat Engine
7. Vision Scanner System
8. Agentic Game Actions
9. Memory & Knowledge Base
10. Bring Your Own Key (BYOK)
11. Offline & Singleplayer Mode
12. Discord Bot Integration
13. Common Issues & Troubleshooting
14. Frequently Asked Questions (FAQ)
15. Privacy & Data Protection Policy

---

# 1. Introduction & Architecture Overview

CraftyAI is an AI companion built by DemonZ Development for Minecraft servers and singleplayer clients. It integrates directly into standard in-game chat, processes player queries, scans blocks and entities via raycasting, executes in-game commands with strict permission safeguards, remembers customized server lore, and provides offline fallback capabilities.

### Platform Support Matrix
- **Plugin (Spigot, Paper, Folia, Purpur):** Minecraft 1.8 through 1.21.x and 26.x.
- **Mod (Fabric):** Minecraft 1.20.4 through 1.21.1, plus 26.x (26.1, 26.2, 26.3+).
- **Mod (Forge):** Minecraft 1.20.4 through 1.20.6.
- **Mod (NeoForge):** Minecraft 26.x.
- **Bedrock Edition:** Supported seamlessly on Java servers running GeyserMC and Floodgate.

---

# 2. Getting Your API Key

Your API key authenticates your Minecraft server or client with DemonZ AI Cloud. Every server receives its own key with isolated rate limits.

### Method 1: Automatic Key Generation (Recommended)
On first server launch, CraftyAI automatically mints an API key and saves it to your configuration file (`plugins/CraftyAI/config.yml` on plugin, or `config/craftyai.json` on mod). The console logs:
```
[CraftyAI] Your new API key: cai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
No manual copying is necessary in CraftyAI v1.3.0+.

### Method 2: Discord Bot
1. Join the DemonZ Development Discord at `https://discord.gg/zCkE44hsBR`.
2. Locate the CraftyAI bot and click **Get API Key**.
3. Provide your server's Session ID (`srv-xxxxxxxx` printed in server console during startup).
4. The bot will DM you the generated API key.

### Key Management Commands
- View current key: `/crafty apikey`
- Rotate compromised key: `/crafty apikey rotate`

---

# 3. Installation: Spigot & Paper Plugin

### Setup Instructions
1. Download `craftyai-spigot-1.3.0.jar` from Modrinth.
2. Place the JAR file into your server's `plugins/` directory.
3. Start the server. The plugin auto-generates `config.yml` and auto-mints an API key.

### Core Configuration (`plugins/CraftyAI/config.yml`)
```yaml
server:
  secret: "cai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

ai:
  name: "Crafty"
  aliases:
    - crafty
    - craftyai
    - ai
    - helper
  enable_actions: true
  allow_block_scanning: true
```

---

# 4. Installation: Fabric, Forge & NeoForge Mod

### Setup Instructions
1. Download the appropriate JAR from Modrinth:
   - For Fabric 1.20.4–1.21.1: `craftyai-fabric-1.3.0.jar` (requires Fabric API).
   - For Fabric 26.x: `craftyai-fabric-26-1.3.0.jar`.
   - For Forge 1.20.4–1.20.6: `craftyai-forge-1.3.0.jar`.
   - For NeoForge 26.x: `craftyai-forge-26-1.3.0.jar`.
2. Place the JAR into `.minecraft/mods/` (client) or `mods/` (dedicated server).
3. Launch Minecraft. Press **K** in-game to open the graphical configuration panel.

### Mod Configuration (`config/craftyai.json`)
```json
{
  "api_key": "cai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "ai_name": "Crafty",
  "ai_enable_actions": true,
  "allow_block_scanning": true
}
```

---

# 5. Server Administrator Guide

### Subscription Tiers
| Tier | Per-Minute Limit | Per-Day Limit | Tokens / Day | Custom Prompts |
|---|---|---|---|---|
| **Free** | 30 req/min | 100 req/day | 50,000 | No |
| **Starter** | 100 req/min | 1,000 req/day | 500,000 | No |
| **Pro** | 200 req/min | 5,000 req/day | 2,500,000 | Yes (1 update/24h) |
| **Enterprise** | 500 req/min | 100,000 req/day | 10,000,000 | Yes (Unlimited) |

### Permissions System
- `crafty.chat`: Allows player to chat with the AI (Default: True for all players).
- `crafty.vision`: Allows raycast block/entity scanning (Default: True).
- `crafty.scan`: Allows `/crafty scan` command (Default: True).
- `crafty.actions`: Master permission for AI action execution (Default: OP only).
- `crafty.actions.gamemode`: Allows AI to change player gamemode (Default: OP only).
- `crafty.admin`: Allows `/crafty reload`, `/crafty learn`, `/crafty memory` (Default: OP only).

### Blocked Dangerous Items
CraftyAI explicitly refuses to give or spawn the following items regardless of player permission tier:
- Command blocks, structure blocks, jigsaw blocks
- Bedrock, end portal frames, barrier blocks, structure voids
- Spawners and end gateway blocks

---

# 6. Natural Chat Engine

Players converse directly in public chat by addressing the AI with any configured alias (`crafty`, `craftyai`, `ai`, `helper`) or prefix (`@crafty`).

### Context Awareness
When generating a reply, the AI automatically receives:
- Player coordinates, biome, dimension, and underground status
- Health, hunger, active potion effects, and armor worn
- Main hand and off-hand items
- World time, weather conditions, and recent conversational history

### Private Queries
Players can use `/crafty ask <question>` or `/ask <question>` for private responses that do not appear in public server chat.

---

# 7. Vision Scanner System

Inspects the entity or block the player is directly targeting via raycast.

### Triggering the Scanner
- **Plugin:** Hold a Compass in your main hand and right-click while looking at a target.
- **Mod:** Look at a target and press the **V** key (rebindable in Minecraft Controls).

### Output Data
- **Entities:** Health/max health, armor, weapons, potion buffs, custom names, and tactical suggestions.
- **Blocks:** Exact block type, block state (crop growth stage, lit furnace state, facing direction), biome, and relative position.

---

# 8. Agentic Game Actions

The AI can perform actions on behalf of players when requested in natural language.

### Supported Actions
1. **Time Modification:** Set to day, night, noon, midnight.
2. **Weather Control:** Clear skies, start rain, summon thunderstorm.
3. **Healing & Nutrition:** Restore health and hunger bars.
4. **Gamemode Switching:** Switch between survival, creative, spectator (requires `crafty.actions.gamemode`).
5. **Item Dispensing:** Gives specified quantities of allowed items with custom enchantments.
6. **Location Finding:** Locates structures (`/locate structure`), biomes (`/locate biome`), or points of interest (`/locate poi`).
7. **Delayed Actions:** Schedules timed actions client-side (e.g. "Teleport me to spawn in 10 seconds").

### Safety Confirmation Safeguard
Destructive actions (such as killing all mobs or altering server gamemodes) require explicit confirmation. The AI prompts the player, who must type `/crafty confirm` before execution.

---

# 9. Memory & Knowledge Base

CraftyAI maintains both short-term conversational context and long-term vector knowledge stores.

### Teaching Custom Lore & Rules
Admins teach the AI with `/crafty learn <question> | <answer>`:
```
/crafty learn What are the server rules? | 1. No griefing. 2. Be respectful. 3. No hacking.
/crafty learn Where is the server shop? | The shop is located at X: 100, Z: -50 in the overworld.
```

### Long-Term Memory (RAG Vector Store)
- Conversations are compressed into semantic vectors.
- Capacity: Free (5 memories), Starter (50), Pro (250), Enterprise (1,000).
- Privacy: All memories are isolated strictly by `srv-xxxxxxxx` session ID and never shared across servers.

---

# 10. Bring Your Own Key (BYOK)

Enables servers to connect directly to third-party AI APIs or local LLM inference engines, bypassing DemonZ AI Cloud request quotas.

### Supported Provider Configurations

#### 1. Google Gemini
- **Endpoint URL:** `https://generativelanguage.googleapis.com/v1beta/openai`
- **Model:** `gemini-3.6-flash`
- **Config Key (Plugin):** `server.custom_provider.api_key`
- **Config Key (Mod):** `"custom_provider_key"`

#### 2. OpenAI
- **Endpoint URL:** `https://api.openai.com/v1`
- **Model:** `gpt-5.6-sol` / `gpt-4o`

#### 3. Groq
- **Endpoint URL:** `https://api.groq.com/openai/v1`
- **Model:** `llama-3.3-70b-versatile`

#### 4. xAI Grok
- **Endpoint URL:** `https://api.x.ai/v1`
- **Model:** `grok-2`

#### 5. Anthropic Claude
- **Via OpenRouter:** URL `https://openrouter.ai/api/v1`, Model `anthropic/claude-3.7-sonnet`.
- **Via LiteLLM Proxy:** URL `http://localhost:4000/v1`, Model `claude-3-7-sonnet-20250219`.

#### 6. Ollama (Local LLM)
- **Endpoint URL:** `http://localhost:11434/v1`
- **API Key:** `ollama`
- **Model:** `llama3.2` / `qwen2.5`

#### 7. LM Studio (Local GUI Inference)
- **Endpoint URL:** `http://localhost:1234/v1`
- **API Key:** `lm-studio`
- **Model:** `local-model`

---

# 11. Offline & Singleplayer Mode

CraftyAI includes robust fallbacks when internet access is unavailable.

### Fallback Modes
1. **LocalBrain (Heuristic Fallback):** When connection drops, LocalBrain handles basic greetings, Minecraft crafting knowledge, and conversational banter with an `[OFFLINE]` chat tag.
2. **Encrypted Request Queue:** Unanswered offline queries are stored in an AES-GCM encrypted local queue (`craftyai_queue.enc`, max 50 items) and replayed once connection is re-established.
3. **Forced Local Mode:** Configure `ai.force-local-mode: true` to run completely offline.
4. **Local LLM Execution:** Configure Ollama or LM Studio under BYOK for complete zero-cloud, privacy-preserving AI generation.

---

# 12. Discord Bot Integration

### Public Player Commands
- `/my-sessions`: Lists all Minecraft servers linked to the user's Discord account.
- `/stats`: Displays daily token and request consumption.
- `/ask <question>`: Queries CraftyAI directly inside Discord.
- `/link <code>`: Redeems a 6-character link code from `/crafty link`.
- `/redeem <key>`: Upgrades a server to a Pro tier subscription.

### Administrator Commands
- `/pro-generate <user> <days> <tier> <reason>`: Issues a Pro key.
- `/pro-list`: Lists active Pro keys.
- `/pro-revoke <key_id>`: Revokes a Pro key.

---

# 13. Common Issues & Troubleshooting

1. **AI Not Responding:** Check `/crafty status`. Verify `cai_...` API key in configuration, outbound port 443 internet connectivity, and firewall rules.
2. **Invalid API Key:** Re-mint with `/crafty apikey` and update configuration.
3. **Mod Crashes on Launch:** Ensure `Fabric API` is installed for Fabric loaders. Verify Java 17+ (Java 25 for Minecraft 26.x).
4. **Rate Limit Reached:** Inspect usage in Discord (`/my-sessions`) or consider upgrading tier / enabling BYOK custom provider.

---

# 14. Frequently Asked Questions (FAQ)

- **Is CraftyAI free?** Yes, the Free tier provides 100 requests per day forever. Pro and Enterprise tiers add higher throughput and custom personality prompts.
- **What AI backend powers CraftyAI?** CraftyAI runs on DemonZ AI Cloud, a proprietary intelligence engine developed by DemonZ Development.
- **Is source code public?** The core clients and backend infrastructure are closed-source and maintained exclusively by DemonZ Development.
- **How to report bugs or get support?** Open a ticket on Discord at `https://discord.gg/zCkE44hsBR`.

---

# 15. Privacy & Data Protection Policy

- **Session Isolation:** All chat histories and vector knowledge memories are strictly indexed against `srv-xxxxxxxx` session IDs. No cross-server data leakage occurs.
- **Encryption:** All client-server traffic is encrypted using HTTPS / TLS 1.3. Local offline queues are encrypted using AES-GCM.
- **BYOK Privacy:** Custom provider requests route directly to the user's chosen endpoint, bypassing DemonZ AI Cloud.
- **Data Deletion:** Server owners may request complete deletion of server memory and session data via Discord support tickets, fulfilled within 7 days.