<center>⚡︎ New Server Runtime – Artificial Intelligence ⚡︎</center>

<center>“The AI Layer for Minecraft Servers.”</center>

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

MC Versions: 1.16 – 1.21.11 • JAR Size: 3.5 MB • AI Models: Gemini, Claude, OpenAI • Highly Optimized

🌐︎ What is NSR-AI?

NSR-AI (New Server Runtime – Artificial Intelligence) is a high-performance AI middleware designed to bridge 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, 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:

24/7 Intelligent Support Agent: Uses RAG (Retrieval Augmented Generation) to provide exact answers from your Knowledge Base, acting as a perfect staff assistant.
Emotional Gameplay Companion: Powering the Pet Emotional System with unique moods (HAPPY, FURIOUS, TIRED), bond levels, and unique relationships.
Dynamic Content Generator: Generates immersive lore-friendly quest descriptions and dialogue that adapt to each player's specific journey.
Privacy-First Player Utility: Allows players to bring their own keys, manage private "checkpoints," and control their own AI environment.
Zero-Stall Middleware: Handles complex AI logic in the background, keeping the server's heartbeat at a perfect 20.0 TPS.
Extensible Developer Framework: A foundation for growth with a robust Open-Source Addon API via the /aia command portal.

🛡︎ 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.
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.yml 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

Zero-Lag Asynchronous AI Engine — Completely decoupled from the Minecraft main thread, NSR-AI 1.4 ensures your server maintains 20 TPS even during heavy AI processing.
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 Middleware & 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 (e.g., Invalid Model - Suggestion: Use a valid model name) 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 1.4

Asynchronous High Performance ⚡ — NSR-AI 1.4 completely decouples the AI engine from the Minecraft main thread. askAI and sendMsg now run entirely in the background, keeping your server at 20 TPS even during complex AI reasoning.
Privacy & Anonymization (Opt-In) 🛡️ — A robust privacy layer allows players to use /ai opt in to anonymize sensitive data (Names, IPs) before sending it to AI providers. This mode also blocks all addon access to player chat for maximum security.
Chat Interception System (Middleware) 🔌 — A powerful new Interceptor API allows addons to read, edit, or cancel player inputs and AI responses in real-time, enabling advanced branding and content filtering.
Universal Command Routing (/aia) 📦 — Addon commands are now cleanly routed via /aia <AddonName>, featuring deep tab completion and a dedicated namespace to prevent command collisions.
Developer API 3.0-pre 🛠️ — A modern builder-pattern API with CompletableFuture support, granular RAG (Knowledge Base) access, and dynamic provider/model overrides per-request.
Stability Hardening & Optimization 💎 — Resolved several critical bugs including addon memory leaks, API key exposure in logs, and pet system logic errors. Massive RAM reduction through inventory stripping and lazy-loading.

🚀︎ How to Setup

Download: Get the latest stable version of NSR-AI.
Install: Place the downloaded .jar file into your server's /plugins folder.
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.
Reload & Go: Start or reload your server. You're all set!

📺 Latest Feature Overview

<details> <summary>📽️ View Other Version Videos</summary>


Version 1.1	Version 1.2-pre
Version 1.2	Version 1.3

</details>

📜︎ 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 — Display 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.
/ai cache <clear|refresh> <player|all> — Manage session history for other players.
/ai memory <clear|refresh> <player|all> — Manage conversation memory for other players.
/aia addon — List all installed addons and their status (Active/Banned/Error).
/aia addon [addon_name] — View version, author, and description for an addon.

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 — Check the current plugin version and update status.
/ai help — Display the dynamic help menu based on your permissions.
/ai shop <item_name> — Query the economy shop for specific item pricing.
/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.
/ai opt <in|out> — Toggle privacy mode (Anonymize names/IPs & block addons).
/ai disable — Instantly deactivate your admin mode session.

API Key Management

/ai apikey — Display the setup guide for session and stored keys.
/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.shop    — Allows players to query shop prices. (Default: true)
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)

<details><summary>Example Configuration (`config.yml`)</summary>

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

default-gemini-model: gemini-2.5-flash
default-claude-model: claude-3-haiku-20240307
default-openai-model: gpt-4-mini
default-api-provider: all # Set to 'all' for automatic provider detection.

api-keys:
  - "YOUR_API_KEY_HERE"

config-version: 2

</details> <details><summary>Example Configuration (`features.yml`)</summary>

# 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)

</details> <details><summary>Directory Tree</summary>

NSR-AI/
├── addons/
│   ├── addon1.jar
│   └── addon1/
├── adminchathistory/
│   └── playername<uuid>/
│       ├── chat-01-01-2026.log
│       ├── chat-31-01-2026.log
│       └── <savedchatname>/
│           └── checkpoint1.blackforge
├── 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.yml
└── privacy.yml

</details>

</center>

🛠 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.
[ 📖 Documentation ] — For technical guides on the Addon API, check the DEVELOPER.md.

Powering your world with smarter gameplay.
Developed by BlackForge Studio