⚡︎ New Server Runtime – Artificial Intelligence ⚡︎

✔ Multi-API • ✔ RAG Knowledge • ✔ Simple & Powerful • ✔ Highly Customizable • ✔ Minimal Lag

MC Versions: 1.16.x – 1.26.x • JAR Size: 6.5 MB • AI Models: Gemini, Claude, OpenAI • Autonomous Tool Calling

🌐︎ What is NSR-AI?

NSR-AI (New Server Runtime – Artificial Intelligence) is a high-performance Minecraft AI plugin that acts as intelligent middleware bridging the gap between advanced Large Language Models and the Minecraft server environment. It is more than a simple chat tool; it is an intelligent ecosystem that weaves AI into the very fabric of your world—from automated staff support to emotionally intelligent companions.

🚀︎ Why Choose NSR-AI?

• Multi-API Sovereignty — You are never locked into one provider. Switch between Gemini, Claude, and OpenAI in real-time.

• Uncompromising Security — With our Triple-Layer Encryption (AES-256-GCM), your API keys are mathematically locked to your server and player UUIDs.

• High-Performance Intelligence — Built on an entirely Asynchronous Pipeline, NSR-AI has very minimal impact on your server's TPS.

• Adaptive Narrative Memory — Through Memory Distillation, your AI remembers your history, your server’s lore, and your players' names.

🛠︎ The Hybrid Intelligence Engine

NSR-AI serves as a multi-role digital infrastructure for your server:

1. 24/7 Intelligent Support Agent: Uses RAG (Retrieval Augmented Generation) to provide exact answers from your knowledge.json base, acting as a perfect staff assistant.

2. Emotional Gameplay Companion: Powering the Pet Emotional System with unique moods (HAPPY, FURIOUS, TIRED), bond levels, and unique relationships.

3. Dynamic Content Generator: Generates immersive lore-friendly quest descriptions and dialogue that adapt to each player's specific journey.

4. Privacy-First Player Utility: Allows players to bring their own keys, manage private "checkpoints," and control their own AI environment.

5. Zero-Stall Architecture: Handles complex AI logic in the background, keeping the server's heartbeat at a perfect 20.0 TPS.

6. Extensible Developer Framework: A foundation for growth with a robust Open-Source Addon API via the /aia command portal.

7. Autonomous Action & Tool Execution: Native stream-based tool calling with 10 universal built-in tools (Auto-Crafting, Inventory Inspection & Sorting, Spatial Radar, Anvil Optimizer, Multi-Command Execution, Interactive Approvals) and dynamic runtime custom tools.

🛡︎ Technical Deep Dives

• Zero-Knowledge Security Standard: Uses three-layer authenticated encryption (AES-256-GCM). Even if your files are stolen, your API keys remain unreadable to anyone else. Filesystem permissions are restricted to owner-only read/write.

• Context-Aware Memory Distillation: Instead of forgetting, the AI "writes a diary" of your conversation. It summarizes history into a single memory message to keep context alive for thousands of messages.

• Staff-Free Knowledge Logic (RAG): Turn your knowledge.json into a living database. The system extracts the "intent" of questions to provide the AI with factual "Cheat Sheets," preventing hallucinations.

• Self-Healing Infrastructure: An automated background system monitors for bugs and applies security patches silently. If one AI provider fails, the system can automatically cycle to a fallback provider.

⚙︎ Core Capabilities

• Autonomous Function Calling & ReAct Agent Loop — NSR-AI transforms from a passive chat assistant into an autonomous in-game companion, evaluating gameplay state in real-time and executing multi-step actions.

• 10 Native Universal Built-in Tools — Hands-free crafting (auto_craft), inventory GUI inspection (get_inventory), 360° environment radar (get_world_environment), long-term memory pins (pin_knowledge), zero-penalty anvil optimization (anvil_enchant_optimizer), inventory sorting and shulker handling (inv_arrange), multi-command batch execution (execute_command), interactive player approvals (execute_command_with_approval), smart command drafting (draft_command_to_chat), and plugin command discovery (plugin_command_lookup).

• Dynamic Custom Tools Engine — Create and hot-reload your own custom AI tools without compiling Java JARs. Supports zero-code declarative YAML (.yml), full JavaScript (.js with Nashorn ES6), folder packages, and anti-zip-bomb protected archives (.zip) directly inside plugins/NSR-AI/custom_tools/.

• Zero-Lag Asynchronous AI Engine — Completely decoupled from the Minecraft main thread, NSR-AI ensures your server maintains 20 TPS even during heavy AI processing and tool executions.

• Privacy & Anonymization Layer — A robust, opt-in privacy system (/ai opt in) that masks player names and IPs before they reach external AI providers.

• Developer API & Interceptors — Advanced API allowing addons to intercept and modify player input or AI responses in real-time.

• Multi-API Integration & Provider Detection — Seamlessly switch between Gemini, Claude, and OpenAI. The system features Automatic Provider Detection for a zero-config setup.

• Smooth API Key Rotation & Load Balancing — Cycle through up to 20 keys automatically. If a key hits a rate limit, the system intelligently falls back to the next key for zero downtime.

• Triple-Layer Security Architecture — API keys are protected by AES-256-GCM encryption across the Server Master Key, the Player Master Key, and the Project Key.

• Advanced Knowledge System (RAG) — Uses Retrieval Augmented Generation and Hybrid Intent Recognition to find precise answers from your lore and facts.

• AI Pet Emotional System — Tame and link pets with unique personalities, moods, and inventories. Includes a secure system to share pet access with friends.

• Advanced Memory & Context Awareness — Features AI-powered Summarization and real-time Context Tracking to keep conversations coherent without lag.

• Master Chat Management — Take complete control of your dialogue history. Save, resume, or delete conversations using /ai chat with Asynchronous Persistent Logging.

• Professional Admin Mode — Access advanced management tools through a secure code. Deactivate instantly by sneaking in-game or using the dedicated command.

• Automatic Configuration Encryption — Any plain-text keys added to config.yml are automatically encrypted the moment the plugin reloads, preventing plain-text leaks.

• User-Friendly Error Handling — Receive clear error messages with actionable solutions to fix issues instantly.

• Proactive Maintenance & Auto-Fixer — An automated system that monitors, downloads, and applies critical Security Patches and Bug Fixes to keep your server stable.

• Unified Add-on System (/aia) — A standardized modular framework where every extension like Player Stats or AFK Tracker is managed through the /aia command portal.

• Sleek UI/UX & AI Awareness — A professional Cyber-Console interface with interactive [Stop], [Edit], and [Regenerate] buttons and animated status indicators.

🚀 What's New in 2.0-pre — The Utility, Automation & Command Mastery Update

NSR-AI v2.0-pre transitions the plugin into a full autonomous in-game companion and command engine with native stream-based tool calling:

📋 Feature Summary Table

🛠️ How to Create Custom Tools Guide

To learn how to create, configure, and code custom tools step-by-step, click on this button:

🔗 Direct URL: https://github.com/BlackForgeStudio/NSR-AI-API/blob/main/CustomTools.md

🚀︎ How to Setup

1. Download: Get the latest stable version of NSR-AI.

2. Install: Place the downloaded .jar file into your server's /plugins folder.

3. Configure: Start your server once to generate the files. Then, open config.yml located in the /plugins/NSR-AI/ folder and add your API key to the api-keys list.

4. Reload & Go: Start or reload your server. You're all set!

🔥 The BlackForge Studio AI Ecosystem Combo 🚀

Turn your server into an interactive, breathing, and responsive world with our three-part AI Ecosystem Combo. These plugins work hand-in-hand to create an unparalleled gameplay experience:

1. NSR-AI Core Engine: The foundation and brain of the server. A high-performance, asynchronous, multi-API Minecraft AI plugin featuring triple-layer encryption, memory distillation, and RAG knowledge base.

2. Advanced Player Stats 3.0 (APS): A standalone analytics engine that hooks into the NSR-AI API. Features Recursive AI Reasoning—the AI can "think" and request player stats (kills, deaths, playtime, bow accuracy, shield blocks, or even chat message length) and invisibly scan inventories to answer player queries (e.g., "Compare the top 3 players' bow accuracy" or "How am I doing?").

3. ChatBuddy 1.0 (CB): A spontaneous, autonomous chat companion. Unlike bots that only speak when commanded, ChatBuddy reads chat and autonomously jumps in using fuzzy keyword matching and Levenshtein distance. Integrates directly with player stats, player death events (with witty remarks), and achievements!

Get all three and build a fully automated, immersive roleplay or support companion setup that will blow your players away!

📜︎ Commands

Admin Commands

/ai admin <activation_code> — Toggle admin mode for advanced features.

/ai admincode — View your private activation code (Requires OP).

/ai data all <page> — Paginated display of all entries stored in the knowledge base.

/ai add <keyword>, <message_content> — Add a new entry (Requires confirmation).

/ai remove <keyword> — Remove a specific entry from the knowledge base.

/ai reload [f|features|nsr-ai|k|knowledge|c|config] — Reload specific plugin components (OP players bypass Admin Mode).

/ai cache <clear|refresh> <player|all> — Manage session history for other players.

/ai memory <clear|refresh> <player|all> — Manage conversation memory for other players.

/ai tools — Display all registered native universal tools and custom tools with live status and version.

/ai tools <name> — Inspect detailed metadata, author, version, type, description, and parameter schema.

/ai tools reload — Hot-reload all custom tools from plugins/NSR-AI/custom_tools/ with zero server downtime.

/ai reload tools — Unified command to hot-reload custom tools from the main reload handler.

/ai migrate — Automatically transfer and backup data from legacy YAML to JSON formats.

/aia addon — List all installed addons and their status (Active/Banned/Error/Inactive).

/aia addon [addon_name] — View version, author, and description for an addon.

/aia plugin — List all registered external API plugins.

/aia plugin [plugin_name] — View detailed metadata for a registered plugin hook.

General Commands

/ai <message> — Start or continue a conversation with the AI.

/ai data <query> — Search the server-specific knowledge base for answers.

/ai settings — Open the interactive GUI to toggle Auto-Summary and change Context.

/ai version or /ai v — View the current plugin version and its full changelog.

/ai version bug — View the changelog for the bug fix module.

/ai version security — View the changelog for the security module.

/ai help — Display the dynamic help menu based on your permissions.

/ai cache <clear|refresh> — Clear or refresh your own conversation session.

/ai memory <clear|refresh> — Summarize and manage your own AI memory.

/ai confirm <code> — Confirm a pending knowledge base action (expires in 120 seconds).

/ai opt <in|out> — Toggle privacy mode (Anonymize names/IPs & block addons from chat).

/ai disable — Instantly deactivate your admin mode session.

API Key Management

/ai apikey — Display the setup guide. (Type this command, then paste your API key directly in chat, or use 'store-[your_key]' to save it permanently).

/ai apikey list — List all your active session and permanent stored keys.

/ai apikey store <projectId> — Permanently store your last session key with an ID.

/ai apikey info [all|key-id] — View usage stats, errors, and fallback history.

/ai apikey model <key-id> <new-model> — Update the AI model for a specific key.

/ai apikey clear [all|key-id] — Delete specific keys or wipe your entire key list.

/ai apikey fallback global <true|false> — Toggle fallback to server keys on failure.

/ai apikey timer <key-id> remove — Reset the "Overloaded" status for a key.

/ai apikey msg save <true|false> — Toggle logging of chats for your active key.

/ai apikey context <id|all> <limit> — Set token limit (e.g., 500, 32k, 128k).

/ai apikey autosummary <id|all> <on|off> — Toggle auto-summarization per key.

/ai apikey autosummary limit <id|all> <%> — Set memory threshold for summary.

Chat Management

/ai chat save <chat-name> — Save your current conversation history.

/ai chat list — List all your saved conversation names.

/ai chat list [chat-name] — View all saved checkpoints for a specific conversation.

/ai chat resume <chat-name> [checkpoint#] — Load a conversation at a checkpoint.

/ai chat delete <chat-name> — Permanently delete an entire saved conversation.

/ai chat delete <chat-name> [checkpoint#|all] — Delete specific or all checkpoints.

AI Pet System

/ai pet — View information and stats for your currently active pet.

/ai pet tame — Link a named pet you are looking at to the AI system.

/ai pet info [pet_name] — View detailed stats, mood, and bond for a pet.

/ai pet nickname <nickname> — Set a unique nickname for your linked pet.

/ai pet inv [pet_name] — Open your pet's inventory.

/ai pet inv allow <pet_name> <player_name> — Grant inventory access to a friend.

/ai pet inv disallow <pet_name> <player_name> — Revoke inventory access.

/ai pet share <pet_name> [allow] [relationship] — Create a 10-minute share link.

/ai pet link list — View which of your pets are shared with others.

/ai pet linked list — View pets owned by other players you are linked with.

/ai pet unlink <pet_name> — Remove your connection to someone else's pet.

Permissions

nsr-ai.use    — Allows players to use the /ai command. (Default: true)

nsr-ai.admin   — Allows players to use admin-specific AI commands. (Default: OP)

nsr-ai.reload  — Allows players to reload the plugin configuration. (Default: OP)

nsr-ai.pet     — Allows players to interact with their pets. (Default: true)

nsr-ai.aia     — Allows players to manage AI addons via /aia. (Default: true)

# NSR-AI Configuration

admin-activation-code: '' # Leave blank to auto-generate



default-gemini-model: gemini-3.8-flash

default-claude-model: claude-sonnet-5-5

default-openai-model: gpt-4o-mini

default-api-provider: all # Set to 'all' for automatic provider detection.



api-keys:

  - "YOUR_API_KEY_HERE"



config-version: 2

# NSR-AI Feature Configuration



# Custom colors for AI and user chat messages.

# Use Minecraft color codes (e.g., &c for red, &a for green).

chat-colors:

  ai: '&b' # Light blue for AI responses

  user: '&7' # Gray for user's chat messages



# Messages displayed to players

messages:

  ai-not-configured: '&cThe AI chat is not configured correctly. Please contact the server owner.'

  api-error: '&cAPI Error: Could not get a response from the AI. Please try again later.'

  permission-denied: '&cI don''t have permission to fulfill that request for you.'

  no-valid-keys: '&cThere are no valid API keys available. Please contact the server owner.'

  all-keys-rate-limited: '&cAll available API keys are currently rate-limited. Please try again later.'

  global-key-fail:

    - '&cThe server''s AI service is temporarily unavailable.'

    - '&cPlease try again in a few moments.'



system-prompt: "You are a helpful AI assistant for a Minecraft server. Your answers should be concise and to the point. Prioritize answering questions about Minecraft. Do not provide code snippets or programming advice. If asked for code, respond with the configured message."



# Auto Memory Refresh (Context Awareness) settings

global-max-context-tokens: 5000 # Maximum tokens the AI can remember in context before auto-refresh

auto-memory-refresh: # This will automatically run '/ai memory refresh' when the player's context reaches the limit.

  enabled: true

  limit: 20 # Threshold percentage (e.g., 20 means it refreshes when 20% context remains)



chat-prefixes:

  ai: '&b[AI]'

  user: '&7[%player_name%]'

  admin-ai: '&c[AI]'



# Code Blocker settings

code-blocker:

  enabled: true

  message: "&cThis is a game built for fun and answering, not for coding."



simple-knowledge-yml-approve: false



command-toggles:

  data: true # Controls /ai data and /ai data all

  admin-disable: true # Controls /ai admin and /ai disable

  version: true # Controls /ai version and /ai v

  add-confirm: true # Controls /ai add and its confirmation

  remove-confirm: true # Controls /ai remove and its confirmation

  reload: true # Controls /ai reload

  memory-clear: true # Controls /ai memory clear command

  memory-refresh: true # Controls /ai memory refresh command

  cache-clear: true # Controls /ai cache clear command

  cache-refresh: true # Controls /ai cache refresh command



# Cooldown settings for AI chat usage

chat-cooldown:

  enabled: false # Set to true to enable a cooldown between /ai commands

  duration: 5000 # Cooldown duration in milliseconds (1000ms = 1 second)

NSR-AI/

├── addons/

│   ├── addon1.jar

│   └── addon1/

├── adminchathistory/

│   └── playername<uuid>/

│       ├── chat-01-01-2026.log

│       ├── chat-31-01-2026.log

│       └── <savedchatname>/

│           └── checkpoint1.blackforge

├── custom_tools/
│   ├── README.txt
│   ├── ban_abusive_player.js
│   ├── claim_daily_reward.yml
│   └── smart_base_defense.js
├── pets/

│   ├── playername<uuid>/

│   │   ├── chats.yml

│   │   └── data.yml

│   └── reserved_nicknames.yml

├── player_keys/

│   └── <uuid>/

│       ├── projectid.yml

│       ├── master.key

│       └── salt.bin

├── playerchathistory/

│   └── playername<uuid>/

│       ├── chat-18-01-2026.log

│       ├── chat-31-01-2026.log

│       └── <savedchatname>/

│           └── checkpoint1.blackforge

├── security/

│   ├── bug.txt

│   ├── master.key

│   ├── master_secret.conf

│   ├── security.jar

│   └── server.salt

├── summarychat/

│   └── playername<uuid>/

│       └── summary.txt

├── config.yml

├── features.yml

├── knowledge.json

└── privacy.yml

🛠 Support & Development

For technical support, bug reporting, and feature tracking, please use our official development channels:

• [ 🐞 Bug Reports ] — Encountered an error? Open an issue via our official templates.

• [ 💡 Feature Requests ] — Have an idea to make the AI smarter? Submit a request via the GitHub issues tab.

• [ 🛠️ Custom Tools Guide ] — Step-by-step developer and administrator guide on building custom tools in JavaScript and YAML.

• [ 📖 Documentation ] — For technical guides on the Addon API, check the DEVELOPER.md.

Powering your world with smarter gameplay.

Developed by BlackForge Studio