advance-player-stats

# <center>⭐ Advanced Player Stats 3.0 ⭐</center> <center><b>“The Intelligence Layer for Minecraft Player Data.”</b></center> --- **✔ Standalone Plugin** • **✔ Agentic Recursive AI** • **✔ Standalone Fallback** • **✔ Dual-Command Routing** • **✔ Minimal TPS Impact** • **✔ Privacy-First** **MC Versions:** 1.16 – 1.21.x • **JAR Size:** ~40 KB • **Requires:** NSR-AI (Optional, for AI features) • **Highly Optimized** --- ## 📊 What is Advanced Player Stats? Advanced Player Stats (APS) 3.0 is a next-generation statistics and privacy ecosystem. Built natively as a **Standalone Spigot/Paper Plugin** (upgraded from the legacy v2 addon), APS bridges raw database logs and user interaction. It functions in **two distinct modes**: 1. **Ecosystem Mode (With NSR-AI):** Turns your server data into an interactive, agentic database where players can chat with "StatsMaster"—an AI persona that understands natural language, scans player inventories, handles complex comparisons, and automatically formats output with custom Minecraft colors. 2. **Standalone Mode (Without AI):** Operates as a lightweight, super-fast stat-tracking plugin. Typos are resolved instantly using an integrated Levenshtein-based **Fuzzy Matching Engine**, falling back to optimized text commands if the AI backend is offline. --- ## 🧠 Dual-Operating Modes: With & Without AI ### 1. 🤖 AI-Hooked Mode (Agentic Recursive Reasoning) When integrated with **NSR-AI** (via a dynamic Java Reflection hook), APS introduces **Recursive Intelligence**: * **Dynamic Context Injection:** When a player asks *"How am I doing?"*, the plugin instantly injects their live vital stats (health, hunger, playtime, afk status) into the AI's short-term memory. * **Recursive Tag Resolution:** Instead of sending massive database dumps to the AI (which wastes token bandwidth), the AI uses an internal **tagging system** (e.g., ``). The plugin intercepts these tags mid-generation, resolves the request against local player data, and feeds the specific answer back to the AI. * **Inventory Grid Scanning:** The AI can query live inventories using ``. The plugin formats a 9x4 grid of the player's main inventory, off-hand, and armor slots, allowing StatsMaster to answer questions like *"Do I have enough gold to craft a golden apple?"*. * **Comparison Engine:** The AI can parse and query multiple players at once (e.g., ``), dynamically retrieving and comparing data to crown the top sniper or mining champion. * **Sovereign API Keys:** Prioritizes the player's individual API key for AI generation, falling back to the server's global key or standard fuzzy commands if keys are missing. ### 2. ⚡ Standalone Mode (High-Performance Fallback) If NSR-AI is missing or fails to load, APS automatically shifts to a robust local fallback: * **Fuzzy Search Engine:** Uses the **Levenshtein Distance Algorithm** to match user inputs. If a player types `/aps stats saksk hlth`, the engine matches `saksk` to `Saksh` and `hlth` to `health`, returning the correct result. * **No API Keys Required:** All commands run 100% locally with zero external network requests. * **Direct Command Line:** Fully functional `/aps` command routes statistics quickly to players through clean, responsive text formatting. --- ## 🛡️ Privacy Sovereignty & Technical Design ### Granular Privacy Controls APS was designed with **Privacy-by-Design** principles. Players retain absolute sovereignty over their metrics: * Using `/aps privacy <feature> `, players can toggle visibility on any stat category. * If a player sets a stat (like `kills`) to `off`, both command requests and AI queries will return ``. The StatsMaster AI is instructed to respect this tag and politely refuse to disclose that specific metric to other players. * Administrators (or players with the `nsr-ai.admin.privacy.bypass` permission) can bypass privacy filters for investigation. ### Coordinate Protection * **Safe Location Tracking:** The location statistic tracks the active dimension/world name (e.g., `world_nether`, `world_the_end`) but **never** stores or reveals coordinates (X, Y, Z). This prevents coordinate exploitation and tracking. ### Minimal TPS Impact Architecture * **Asynchronous I/O:** Stat increments are tracked on the main thread via Spigot listeners, but all database reads, writes, and AI requests run asynchronously on a background Bukkit runnable (`1200L` / 60-second intervals) to ensure minimal main-thread performance cost. * **UUID-Indexed Storage:** Player data is saved in structured, clean YAML files (`plugins/Advanced-Player-Stats/playerdata/{UUID}.yml`), preventing index corruption. --- ## ⚔️ Complete Analytics Portfolio (29 Stats) APS 3.0 tracks a massive array of metrics, categorized below: ### 👤 General & Vitals * **Playtime** — Total active time spent playing on the server (updated asynchronously