NSR-AI Version 1.1-pre2

(Released: 2025-09-03)

Overview

NSR-AI is a next-generation AI plugin for Minecraft servers, designed to bring intelligent conversations, admin tools, and extensibility directly in-game.

It supports Gemini, Claude, and OpenAI APIs, making it one of the most flexible AI plugins available. With its addon system, server owners can expand functionality, while players enjoy smooth, natural interactions.

The latest release, v1.1-pre2 (2025-09-03), focuses on stabilizing addons, improving performance, and fixing issues from pre1 before the full 1.1 release.

🆕 What's New in Version 1.1-pre2

  • Admin-Only Knowledge Base Management: /ai add and /ai remove are now restricted to admin mode.
  • Secure Confirmation System: A 6-digit confirmation code is required for all knowledge base changes.
  • AI-Powered Content Correction: /ai add now auto-corrects grammar and spelling.
  • AI-Generated Headings: Automatic descriptive headings for new knowledge entries.
  • Separated Queries: /ai data <question> for knowledge base, /ai <message> for general chat.
  • Enhanced Fuzzy Matching: Smarter knowledge base search for more relevant results.
  • Asynchronous API Calls: Prevents lag by running AI calls in the background.

Available Commands

  • /ai <message>
    Example: /ai Hello, how are you?
    → The AI replies directly in chat.
  • /ai admin <code>
    Example: /ai admin 123456
    → Activates Admin Mode for the player BlackForge using the secure code.
  • /ai disable
    Example: /ai disable
    → Disables Admin Mode for BlackForge and returns AI to normal usage.
  • /ai add <content>
    Example: /ai add Our server rules: Be respectful, no griefing, and have fun.
    → The AI corrects grammar, generates a heading, and prepares this entry for confirmation.
  • /ai confirm <code> [keyword]
    Example: /ai confirm 654321 rules
    → Confirms the previous addition to the knowledge base with the keyword “rules” for reference by BlackForge.
  • /ai remove <question>
    Example: /ai remove What are the server rules?
    → Removes the knowledge base entry associated with that question.
  • /ai data <question>
    Example: /ai data What are the server rules?
    → Retrieves the stored knowledge base answer for BlackForge to review.
  • /ai reload
    Example: /ai reload
    → Reloads the plugin configuration and any updated knowledge base entries.

Command Permissions

  • /ai <message> → Permission: nsrai.chat (default: all players)
  • /ai admin <code> → Permission: nsrai.admin (default: ops only)
  • /ai disable → Permission: nsrai.admin
  • /ai add → Permission: nsrai.admin
  • /ai confirm → Permission: nsrai.admin
  • /ai remove → Permission: nsrai.admin
  • /ai data → Permission: nsrai.admin (view knowledge base)
  • /ai reload → Permission: nsrai.admin (reload configuration)

By default, player chat with /ai is open to everyone, while management commands are restricted to operators or players with nsrai.admin permission.

Key Features

  • Addon System: Modular plugin architecture allowing addons to extend AI abilities (e.g., Player Stats, Quests, Economy). v1.1-pre2 introduces improved stability, error handling, and a richer developer API.
  • Performance Optimizations: Reduced CPU and memory usage, asynchronous API calls for lag-free execution, and AI response caching for instant replies to common queries.
  • Admin Controls: Secure /ai admin <code> activation, /ai disable for quick shutdown, and full knowledge base management with /ai add, /ai confirm, and /ai remove.
  • Knowledge Base: Persistent server-specific memory; AI auto-corrects grammar, generates titles, and uses fuzzy matching for relevant answers.
  • Player Interaction: Natural chat with /ai <message>, supports Gemini, Claude, and OpenAI APIs, remembers context, and integrates with player stats through addons.
  • Security & Safety: Built-in code blocker to prevent unsafe code sharing, retry mechanisms for failed calls, and clean chat formatting to avoid spam.
  • Compatibility: Works with Minecraft 1.16–1.21 and multiple Java environments, designed for scalability and future addon support.

All Features of NSR-AI

  • Multi-API Integration: Supports Gemini, Claude, and OpenAI. You can switch providers at any time to balance speed, intelligence, and cost.
  • Lightweight & Optimized: Designed for high performance with a small JAR size (~3MB) and minimal impact on server resources.
  • Custom Chat Presentation: Fully customizable colors and prefixes for AI and player messages to fit your server’s theme.
  • API Key Rotation: Supports up to 20 API keys, automatically cycling between them to avoid rate limits and downtime.
  • Persistent Knowledge Base: Store server rules, FAQs, and custom information that the AI remembers across restarts.
  • Admin Mode: Secure admin-only mode with /ai admin and /ai disable. Only admins can manage the knowledge base.
  • Knowledge Base Management: Add, confirm, remove, and query entries using AI-assisted commands. The AI corrects grammar and generates headings automatically.
  • Secure Confirmation System: A 6-digit confirmation code is required for all knowledge base changes, ensuring no accidental edits.
  • Separated Queries: Use /ai data <question> to query the knowledge base and /ai <message> for normal AI chat.
  • Enhanced Knowledge Search: Advanced fuzzy matching ensures the AI finds the most relevant answers, even with misspelled or varied phrasing.
  • AI-Powered Content Correction: The AI improves text when adding knowledge entries by fixing grammar and spelling automatically.
  • AI Self-Description: The AI can introduce itself and explain its features to players when asked.
  • Code Blocker: Built-in security feature that prevents unsafe code from being shared in chat.
  • Asynchronous API Calls: All AI requests run in the background to prevent server lag and improve stability.
  • Enhanced Error Handling: User-friendly error messages make issues easier to understand and fix.
  • Addon System: Extend functionality by dropping addon .jar files into the addons folder. This makes the plugin future-proof and customizable.
  • Advanced Player Stats Addon: Optional addon that tracks kills, deaths, AFK time, playtime, and blocks mined, with built-in privacy controls and AFK detection.
  • Powerful Yet Simple: Easy to install, lightweight, and powerful — making it one of the most flexible AI plugins available for Minecraft servers.

Improvements & Bug Fixes

  • Addon Configurations: Fixed issues where certain addon setups could result in console spam or unstable logs.
  • AI Response Looping: Resolved a rare bug where the AI would generate repetitive or looping answers in some conversations.
  • Compatibility: Improved stability across Minecraft versions (1.16–1.21) and broader Java environments for smoother operation.
  • Documentation: Updated and clarified setup instructions, making it easier for new admins to configure the plugin.

Optional Dependencies

  • PlaceholderAPI: Allows you to use NSR-AI placeholders in other plugins.
  • NSR-AI-Advanced-Player-Stats (Addon): Optional addon that provides detailed player stats, privacy controls, and an AFK tracker.

Configuration (config.yml)

# NSR-AI Configuration

# The secret code to enter admin mode.
admin-activation-code: '3637'

# Custom colors for AI and user chat messages.
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 API keys are currently rate-limited. Please try again later.'

# Default AI models
default-gemini-model: gemini-1.5-flash
default-claude-model: claude-3-opus-20240229
default-openai-model: gpt-4
default-api-provider: all

# List of API keys
api-keys: ["your_key_here"]

# AI behavior system prompt
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."

# Chat memory settings
conversation-history-length: 10

# Chat prefixes
chat-prefixes:
  ai: '&b[AI]'
  user: '&7[You]'
  admin-ai: '&c[AI]'

# Chat history settings
chat-history:
  enabled: true
  max-size: 100

# Code Blocker settings
code-blocker:
  enabled: true
  message: "&cThis is a game built for fun and answering, not for coding."

# Versioning
config-version: 2

⚙️ How to Setup the Config

  • admin-activation-code: '3637'
    This is the secret code used to activate Admin Mode with /ai admin <code>. You can change it to any letters and numbers.
    Recommendation: Always change this from the default so others cannot access admin mode.
  • chat-colors:
    Controls the chat colors for AI and player messages.
    Example: ai: '&b' makes AI text light blue, user: '&7' makes player text gray.
    Use Minecraft color codes like &a, &c, &e to customize.
  • messages:
    Custom error and system messages shown to players.
    Example: api-error shows when the AI cannot respond.
    Tip: Edit these messages to match your server style.
  • default-gemini-model: gemini-1.5-flash
    default-claude-model: claude-3-opus-20240229
    default-openai-model: gpt-4
    default-api-provider: all
    Sets which AI model and provider the plugin will use by default.
    - If set to all, the plugin automatically detects the API key type (Gemini, Claude, OpenAI).
    - If you set it to one provider (e.g. gemini), all keys will be treated as that provider.
    Recommendation: Keep it as all for flexibility.
  • api-keys: ["your_key_here"]
    Add your API keys here. Supports up to 30 keys.
    Example: ["key1","key2","key3"].
    Recommendation: Use multiple keys to avoid rate limits.
  • system-prompt:
    Controls how the AI behaves. Default makes it a helpful Minecraft assistant.
    Tip: Change this if you want the AI to roleplay, enforce rules, or act differently.
  • chat-prefixes:
    Sets what appears before AI and player messages.
    Example: Default is [AI]. If changed to [ChatGPT], messages will show like [ChatGPT] <message>.
  • chat-history:
    Decides if chat history is saved and how much is remembered.
    Example: max-size: 100 saves the last 100 messages per player.
  • code-blocker:
    Stops the AI from sending code in chat. You can change the warning message.
    Recommendation: Keep it enabled for security.

📥 How to Install NSR-AI

  • Click here if not downloaded. Available on both Polymart and SpigotMC.
  • Add the Plugin: Place NSR-AI.jar into your server’s plugins folder.
  • Start the Server: Run your server once. The plugin will create a NSR-AI folder with default configuration files.
  • Edit the Config: Open config.yml inside plugins/NSR-AI/. Add your API keys, set up admin code, and adjust settings.
  • Restart the Server: After editing config.yml, restart the server so changes take effect or if you are admin you can type /ai reload reloads the config..

📂 Directory Structure

plugins/
└── NSR-AI/
    ├── addons/               # Place addon .jar files here (optional)
    ├── playerChatHistory/    # Stores all player chat logs
    ├── adminChatHistory/     # Stores all admin chat logs
    ├── knowledge.yml         # Knowledge base entries
    └── config.yml            # Main configuration file

Known Issues

  • Addon API Documentation: Full developer documentation for the addon system is still pending and will be released with the stable 1.1 update.
  • Complex AI Behaviors: Some advanced or multi-step AI interactions may require additional fine-tuning for best performance, and could occasionally behave unpredictably.
  • Addon Developer Support: While the API has been expanded, examples and tutorials are still limited, which may make it harder for new developers to create addons.