NSR-AI v1.4 — The Developer Empowerment Update

Plugin Version: 1.4  |  API Version: 3.0-pre  | 

NSR-AI v1.4 is the most significant update for developers and server owners to date. This release transforms NSR-AI from a standalone tool into a full-fledged Development Platform — featuring a completely rebuilt programmatic API, granular AI controls, a powerful chat interception layer, and deep stability hardening across every system in the codebase. Whether you're a server admin who wants plug-and-play reliability, or a developer building on top of NSR-AI, this update delivers.

---

📋 Quick Summary

Area	What's New
🆕 New Features	Privacy system, Pet API, session control, command routing, middleware, and more
🐛 Bug Fixes	Several critical, security, pet, and engine stability fixes
⚡ Optimization	Major RAM reduction, CPU hardening, and full codebase consolidation
🛠️ Developer API	Builder-pattern registration, async futures, interceptors, RAG access

---

🔗 Jump To Section

🆕 New Features  ·  🐛 Bug Fixes & Stability  ·  ⚡ Performance & Optimization  ·  🛠️ Developer API

---

🆕 New Features

⚡ Asynchronous High Performance

NSR-AI v1.4 completely decouples the AI engine from the Minecraft main thread, keeping your server running smoothly at all times.

• Zero-Lag AI Requests: askAI and sendMsg now run entirely in the background — your server stays at 20 TPS even during complex AI reasoning.
• Async Persistence: Saving AI logs via SaveMsg or updating the Knowledge Base no longer causes disk lag or server hiccups.
• Future-Ready API: All critical paths now use CompletableFuture, giving developers precise control over when to handle AI responses without blocking the game thread.

---

🔌 Chat Interception System (Middleware)

NSR-AI 1.4 introduces a powerful Interceptor System that allows addons to sit between the player and the AI, enabling custom processing at every stage of a conversation.

Middleware Capabilities

Addons can now register an AIInterceptor to:

• Read & Edit Player Input — Modify what the player says before it reaches the AI.
• Read & Edit AI Response — Transform the AI's answer (e.g. add branding or filter content) before the player sees it.
• Cancel Interactions — Block specific inputs or responses based on custom logic (e.g. filtering bad words or enforcing game rules).

Knowledge Base Bridge (RAG Access)

• Programmatic Access: Addons can now query and mutate the knowledge.yml store directly.
• Hierarchical Permissions: read-knowledge and edit-knowledge nodes control access globally and per-addon.
• Addon Identification: The core plugin now uses stack-trace analysis to verify which addon is making an API call, preventing unauthorized knowledge tampering.

Smart System Prompt Injection

• Core Context Extension: Addons can use the onSystemPrompt interceptor to append dynamic instructions to the /ai global system prompt.
• API Isolation: When an addon calls askAI or sendMsg, the core NSR-AI system prompt is bypassed, allowing the addon to supply its own pure system instructions.

Universal Command Routing (/aia)

• Addon Namespace: Commands are now routed via /aia <AddonName>, keeping /ai exclusively for core features.
• Tab Completion Delegation: The core plugin handles the first argument (addon list) and then delegates all subsequent arguments and tab suggestions to the target addon.
• SimpleAddon Builder: Enhanced to support .onTabCompleteHandler() for rapid development.

Integrated Pet System API

• AIPet Data Model: Addons can now programmatically access pet details (Name, Mood, Bond, Level, Hunger, etc.).
• Dynamic Manipulation: New API methods allow addons to change a pet's mood, bond, or level on the fly — perfect for RPG or training addons.
• Status Interrogation: Fetch a list of all pets owned by a player to display in custom GUIs or menus.

---

🛡️ Advanced Permission Architecture

With great power comes great responsibility. NSR-AI 1.4 adds a multi-layered permission system to keep your server secure.

• Global Master Switch: A central permissions.yml allows admins to disable chat reading or editing for all addons at once.
• Automatic Per-Addon Folders: NSR-AI automatically creates a dedicated folder and permissions.yml for every registered addon.
• Granular Permissions: Control exactly what each addon can do — read-player-input, edit-ai-response, cancel-player-input, and more.

---

🧠 Smart AI Routing

The internal engine has been upgraded with intelligent routing logic that handles multi-provider setups seamlessly.

• Provider Sovereignty: Automatically detects whether a key is Gemini, Claude, or OpenAI and formats the request perfectly for each provider.
• Dual-Mode Intelligence: Automatically switches between Player API keys and Global Fallback keys based on developer requirements.
• Thread-Safe Memory: Shared memory and conversation histories are now handled with full thread-safety, ensuring data integrity during async operations.

---

🔄 Advanced Session & Memory Control

Developers now have granular control over how the AI remembers and forgets across conversations.

• Summarize Chats: Compress long conversations into a summary that the AI retains in its memory.
• Cache Refresh / Clear: Manually reload a conversation session from disk or wipe it entirely for a fresh "clean slate."
• Memory Access: Programmatically read, update, or clear the AI's long-term summaries for each player.
• Shared Memory Store: A global key-value store that allows different addons to share context with each other.

---

🛠️ Flexible Component Reloading

You no longer have to reload the entire plugin for a small change. The new API supports targeted reloads for any component:

Mode	What It Reloads
FULL	Everything
CONFIG	config.yml only
KNOWLEDGE	RAG knowledge base only
FEATURES	Feature toggles only

---

⚡ Dynamic Model & Provider Control

Take full control over the AI engine programmatically, without ever restarting the server.

• Global Swapping: Change the server's default model or API provider (Gemini, OpenAI, Claude) on the fly via the API.
• Per-Request Overrides: Addons can specify a different model or provider for a specific request without affecting global settings — perfect for complex tasks that require a "Pro" model.

---

🏗️ Structured Addon Command Aliases

NSR-AI 1.4 overhauls how addons integrate commands into the server, providing a clean, collision-free namespace.

• Dedicated Namespace: Addons use /aia, leaving /ai exclusively for core plugin features.
• Custom Aliases: Every addon can define a short "Main Command" alias (e.g. /aia aps).
• Deep Tab Completion: Addon aliases are automatically suggested, and sub-commands are fetched directly from the addon for a professional, native feel.
• Collision-Free Routing: Commands are routed based on aliases, preventing multiple addons from conflicting with each other.

---

🛡️ Privacy & Anonymization (Opt-In / Opt-Out)

NSR-AI 1.4 introduces a robust privacy layer that gives players full control over their data.

• Privacy Mode (Opt-In): Players can use /ai opt in to enable maximum privacy. This swaps sensitive information (like Player Names and IPs) with random codes (e.g. PlayerName → R2d13n) before sending data to the AI. It also blocks all addon and plugin access to the player's chat, preventing any middleware from reading or editing their AI interactions.
• Normal Mode (Opt-Out — Default): By default, NSR-AI uses real names and allows registered addons to process messages normally, ensuring maximum compatibility with AI extensions.
• New Command: /ai opt <in|out> allows players to toggle between modes instantly.

---

📜 V1 Legacy Support & Clean-up

To ensure a smooth transition from older versions, NSR-AI v1.4 retains 100% backward compatibility for all core chat addons from v1.2 and v1.3 (AIMessage & AIResponse systems).

---

🐛 Bug Fixes & Stability

NSR-AI 1.4 has been hardened with several critical stability and security fixes across all major systems.

🔴 Critical Fixes

• Addon Unload Loop: Fixed a critical bug where only the first addon was unloaded during /ai reload. All other addons remained as ghost instances in memory, causing duplicates, memory leaks, and unpredictable behavior after every reload.
• API Key Selection Ignored Overload: The key rotation system had broken logic that could return a rate-limited key back to the caller, causing 429 Too Many Requests errors to cascade to players. Now properly consults the OverloadedKeyManager before selecting a key.
• API Key Leaked in Logs: When a global API key was rate-limited, the full raw key was printed to the server console — a serious security vulnerability. Now only the last 4 characters are shown (e.g. ***a1b2).
• Plugin/Addon Registration Bypass: registerPlugin() and registerAddon() accepted any plugin or addon without checking the security ban list, allowing a banned addon to bypass restrictions by registering programmatically. Both methods now validate against SecurityManager before granting access.

---

🛡️ Privacy & Security

• Smart Anonymization: Fixed a bug where names could be partially replaced (e.g. "Bob" inside "Bobby"). Now uses Regex word boundaries to ensure only exact name matches are anonymized.
• Robust De-anonymization: Added case-insensitive matching for privacy codes to ensure AI responses are always correctly converted back to real player names.
• IP Protection: Hardened IP detection logic to prevent data leaks to external AI providers.
• Plugin-Level Banning: Added validatePlugin() to SecurityManager so entire Bukkit plugins (not just addons) can be banned. The API bridge is severed at runtime with a clear log warning, and the fix is fully backward compatible with older security JARs.

---

🐾 Pet System Robustness

• Fixed Immortal Pets: Pets now correctly lose health when damaged. Fixed a logic error where health was reset to max every game tick.
• Dynamic Hunger & Health: Pet status bars are no longer stuck at full. Hunger now decreases over time, and pets only regenerate health if well-fed (Hunger > 80).
• NPE Prevention: Added safeguards for unsupported entity types and pets without nicknames, preventing console errors during pet interactions.

---

⚙️ Core Engine Stability

• Thread-Safe Memory: Migrated conversation history to CopyOnWriteArrayList to prevent ConcurrentModificationException during asynchronous AI processing.
• Thinking Animation Safety: Added null-checks to the thinking animation system to handle player disconnections gracefully.
• Task Management: Optimized background tasks to prevent task accumulation during plugin reloads.
• ChatLogger Null Guard: Fixed a NullPointerException crash when chat logging was disabled in config but players were actively chatting.
• Knowledge Base Save Fix: Fixed a data corruption bug where the knowledge base could become unreadable after saving if any keyword contained dots or special YAML characters. Entries are now written individually with proper YAML path notation.
• Player Quit Cleanup: Removed a duplicate clearApiKeys() call that was causing unnecessary overhead on player disconnect.

---

⚡ Performance & Optimization

⚡ API Infrastructure Stabilization (The GitHub Transition)

Due to significant usage spikes observed recently, we have overhauled our update and security infrastructure to ensure 100% uptime and reliability.

• Cloudflare to GitHub Migration: The update and security fetch engine has been migrated from dynamic Cloudflare Workers to a high-performance, static GitHub-hosted manifest architecture.
• Unified Fetch Logic: The plugin now performs a single, consolidated fetch for all versioning, security, and bugfix data, drastically reducing network overhead and preventing request-related throttles.
• Local Filtration Engine: Implemented client-side version matching for bug fixes. The plugin now downloads the global manifest and identifies relevant patches locally, removing server-side processing dependencies.

Core Infrastructure Hardening

• Runtime Security Bridge: Implemented validatePlugin and validateAddon in SecurityManager. Banned plugins are now disconnected at registration time, preventing unauthorized API access.
• Thread Safety Overhaul: Converted all critical plugin maps (admin status, cooldowns, shared memory) to ConcurrentHashMap to prevent ConcurrentModificationException during async API operations.
• API Reliability: Fixed "dummy" retry logic — the plugin now properly attempts 3 retries with exponential backoff for failed AI requests.
• Personal API Key Privacy: Added hooks to PlayerListener to respect privacy settings — players who opt out of privacy will no longer have their chat logged by the global ChatLogger.
• Manager Stability:
  • PlayerDataManager: Fixed unsafe inventory casting and added default value safety for all player stats.
  • ApiKeyManager: Fixed Claude/OpenAI validation endpoints (now uses POST for Claude and /v1/models for OpenAI).
  • ConversationManager: Fully converted to CopyOnWriteArrayList for consistent thread-safe history management.
• Shutdown Persistence: Added explicit save calls in onDisable for Knowledge Base and Saved Chats to ensure zero data loss during server restarts.

---

Utility & Performance Optimization

• Massive Masking Optimization: Refactored ChatLogger key masking to eliminate an O(N×M) bottleneck. The logger no longer scans every player's key for every message — it now targets only relevant keys, drastically reducing CPU usage on large servers.
• Utility Thread Safety:
  • ConfirmationManager: Migrated to ConcurrentHashMap for fail-safe async cleanup.
  • AdminRecipientManager: Implemented CopyOnWriteArrayList to prevent broadcast crashes.
• Logic Hardening:
  • StringUtil: Fixed Levenshtein matching to prevent false-positive "best matches" when input confidence is low.
  • UpdateChecker: Hardened version parsing to support complex version strings (e.g. -pre, -alpha) without numeric parsing errors.
• Data Integrity: Added UUID parsing guards in AdminRecipientManager to handle manual configuration errors gracefully.

---

Pet System Hardening (Final Stability Pass)

• Performance Overhaul: Refactored PetListener chat processing to only scan relevant pets, eliminating O(N) server-wide scans and preventing chat-induced TPS drops. Implemented Regex Pattern caching on the Pet object itself to prevent thousands of expensive regex recompilations during chat events.
• RAM Optimization (Lazy Loading): Rewrote PetDataStorage and Pet inventory handling. The server no longer creates empty Bukkit Inventory objects in memory for every loaded pet — inventories are now fully lazy-loaded on demand, saving significant heap memory on servers with large numbers of pets.
• Thread-Safe Concurrency: Converted all internal mapping structures inside PetManager to ConcurrentHashMap (replacing unsafe HashMap instances) and implemented ThreadLocal date formatting in PetDataStorage. This entirely eliminates the risk of ConcurrentModificationException during async pet chat processing.
• Feature Completion: Fully implemented missing subcommands in /ai pet (share, link-redeem, unlink), bridging the gap between command usage and backend logic.
• Logging Precision: Upgraded pet chat logs to millisecond precision to prevent message overwrites during rapid-fire AI conversations.

---

Manager Architecture Hardening (Final Platform Audit)

• Universal Thread-Safety: All internal managers (Knowledge, Privacy, Settings, Shop, Addon, Data, ActiveConversation, SaveChat) have been fully migrated to ConcurrentHashMap and thread-safe data structures. This eliminates the risk of ConcurrentModificationException during high-frequency AI interactions.
• Atomic File Persistence: Implemented synchronized file locks for all YML and Binary storage managers. This prevents data corruption during simultaneous async AI responses and ensures player settings, API usage counts, and chat histories are always saved correctly.
• High-Performance Caching:
  • PermissionManager: Now features a memory-based permission cache, eliminating redundant disk I/O on every permission check — removing a primary source of server stutters.
  • PlayerDataManager: Implemented a memory cache for player stats, ensuring the AI can access player context instantly without disk reads.
• Addon Management System Hardening:
  • Memory-Direct Loading: Refactored AddonManager to eliminate expensive temporary file creation/deletion when scanning addon JARs. Metadata is now read directly from the JAR stream via InputStreamReader, removing a major source of disk I/O lag and preventing file-lock errors.
  • API Modernization: Marked the legacy Addon interface as @Deprecated to streamline the v1.5 transition while maintaining full v1.4 backward compatibility.
  • Memory Leak Prevention: Implemented try-with-resources for all Addon JAR loading, ensuring URLClassLoader and JarFile handles are closed properly.
• Config & Resource Integrity:
  • Resource Leak Fix: Hardened ConfigUpdater with try-with-resources for default configuration streams, preventing stranded file descriptors during repeated plugin reloads.
  • UTF-8 Enforcement: Standardized on StandardCharsets.UTF_8 for all configuration and addon metadata reading, ensuring consistency across different server locales.
  • Non-Destructive Updates: Hardened ConfigUpdater to be additive-only, safely preserving custom user keys and data across version upgrades.

---

Extreme Optimization & RAM Efficiency (The Performance Overhaul)

• Massive Codebase Consolidation:
  • Refactored fragmented AI calling logic into a unified core pipeline.
  • Deleted nearly 500 lines of redundant code across 12+ legacy provider methods (Summarization, Grammar, Headings, Extraction).
  • Legacy Data Package Archiving: Safely commented out the entire com.nsr.ai.plugin.data package (14 legacy DAO classes). This unused skeleton code is now archived, preventing accidental compilation, reducing the final JAR size, and shrinking the overall codebase footprint.
  • The plugin is now significantly smaller, faster to load, and easier to maintain.
• Critical RAM Reduction:
  • Inventory Stripping: Removed ItemStack inventory caching from the PlayerData object. Data is now fetched directly from the online player only when needed, reducing heap memory usage by up to 90% on high-player-count servers.
  • Conversation TTL (Time To Live): Implemented an automated background task that purges inactive conversation histories from memory after 30 minutes of inactivity.
• CPU & Lag Prevention:
  • Direct Search Algorithm: Optimized KnowledgeManager search logic to perform direct iteration, eliminating expensive HashMap copying on every query.
  • Resource Singletons: Standardized Gson and OkHttpClient as shared, high-performance singletons across all managers.
  • Event Handler Cleanup: Removed empty event listeners (e.g. onPlayerMove) to ensure the plugin has zero idle CPU overhead for non-AI tasks.
• Persistence Hardening: Optimized PlayerDataManager and ConversationManager to ensure all data is persisted with atomic safety during async operations.
• Cryptographic & Utility Speedups:
  • Encryption Cache: Implemented a ConcurrentHashMap cache for PBKDF2 key derivation in EncryptionUtil and SecurityUtil, eliminating massive CPU spikes during data decryption and player-specific key generation.
  • ThreadLocal Caching: Refactored ChatLogger to use ThreadLocal<SimpleDateFormat>, preventing thousands of unneeded object allocations per minute during heavy logging.
  • StringBuilder Refactor: Replaced inefficient string concatenation in MessageFormatter with StringBuilder, significantly reducing memory fragmentation and garbage collection pauses.
  • Randomness & String Optimization: Consolidated SecureRandom and ThreadLocalRandom usage for faster generation. Lifted invariant string transformations out of loops in StringUtil and pre-compiled Regex patterns in UpdateChecker for tighter execution.
• Targeted Manager Optimizations:
  • ActiveConversation CPU/Memory: Completely removed the animationFrame tracking map from ActiveConversationManager. By utilizing localized closure state within the BukkitRunnable, thousands of auto-boxing memory allocations and map mutation operations that previously occurred every second during active AI conversations are now eliminated.
  • BugFixManager Memory: Removed private OkHttpClient and Gson instantiations, routing requests through the plugin's global singletons to eliminate duplicate thread pools.
  • ShopManager CPU: Extracted and pre-compiled the shop query Regex Pattern (SHOP_QUERY_PATTERN), stripping a heavy Pattern.compile() call out of the high-frequency chat event path.
  • AddonInfo Safety: Marked all fields as final, guaranteeing immutability and enabling JVM memory access optimizations for addon metadata DTOs.

---

🛠️ Developer API

API Version: 3.0-pre  |  Fully backward compatible with v1.2 and v1.3 addons.

NSR-AI 3.0-pre replaces the old, complex registration system with a modern, builder-pattern API that makes integration effortless. All critical paths are async-first, giving developers full control without blocking the game thread.

1. Simple Addon & Plugin Registration

Register your extension with a single line of code. NSR-AI handles all the complex reflection and internal logic automatically.

// Register a native NSR-AI addon
NSRAI.getAPI().registerAddon(myAddon);

// Register an existing Bukkit plugin that wants AI features
NSRAI.getAPI().registerPlugin(myPlugin, myAddon);

• registerAddon(AIAddon) — For native NSR-AI extensions.
• registerPlugin(Plugin, AIAddon) — For existing Bukkit plugins that want to add AI features.

---

2. Flexible AI Parameters (Temperature, Top-P, Top-K)

You no longer have to settle for the default AI "brain." Developers can programmatically adjust how the AI thinks for each specific request:

• Temperature — Control creativity vs. factual precision.
• Top-P & Top-K — Fine-tune the probability distribution of the AI's word selection.
• Max Tokens — Set strict limits on response length to control costs.
• Custom Settings — Inject ANY provider-specific parameter (e.g. OpenAI's presence_penalty) directly into the JSON request body.

---

3. Async CompletableFuture API

All API calls are fully non-blocking. Use standard Java CompletableFuture chains to handle responses cleanly.

api.askAI(player, "What is the weather today?")
   .thenAccept(response -> player.sendMessage(response))
   .exceptionally(err -> { err.printStackTrace(); return null; });

---

4. Knowledge Base (RAG) Access

// Read from the knowledge base
String info = api.getKnowledge("server-rules");

// Write to the knowledge base
api.setKnowledge("server-rules", "No griefing allowed.");

Requires the read-knowledge / edit-knowledge permissions to be granted to your addon in its permissions.yml.

---

5. Session & Memory Management

// Summarize a player's conversation history
api.summarizeChat(player);

// Clear a player's conversation session
api.clearSession(player);

// Access shared memory between addons
api.getSharedMemory().put("my-key", "my-value");

---

6. Interceptor Registration

api.registerInterceptor(new AIInterceptor() {
    @Override
    public String onPlayerInput(Player player, String input) {
        return input.replace("badword", "***"); // Edit input before it hits the AI
    }

    @Override
    public String onAIResponse(Player player, String response) {
        return "[MyAddon] " + response; // Add branding to responses
    }
});

---

7. Dynamic Model & Provider Override

// Override the model for a single request
AIRequest request = new AIRequest(player, "Summarize this:")
    .withModel("gemini-1.5-pro")
    .withProvider(AIProvider.GEMINI);

api.askAI(request).thenAccept(player::sendMessage);

---

Developer-First. Admin-Controlled. Hardened Security. Effortless Integration. NSR-AI 1.4 — The Platform for Intelligence. 🎮 ⚡ 🧠