⭐ Advanced Player Stats 3.0 ⭐

✔ 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., [TYPE:PlayerName,kills,deaths]). 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 [TYPE:PlayerName,inventory]. 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., [TYPE:Steve,stats][TYPE:Alex,stats]), 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> [on|off], 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 [PRIVATE]. 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 in background tasks).
• Times Joined — Tracks the number of unique login sessions.
• Health — Monitored current health status.
• Hunger — Real-time tracking of food level status.
• AFK Status — Detects if a player is currently away from keyboard.
• AFK Time — Accumulates total time spent in AFK mode.
• Location Context — Tracks the current dimension/world safely without leaking coordinates.

⚔️ Combat & Accuracy Profiling

• Player Kills — Total other players defeated in PvP.
• Total Deaths — Total times a player has died.
• Kill/Death Ratio (K/D) — Computes the PvP efficiency of a player.
• PVP Kill Streak — Tracks consecutive player kills without dying.
• Bow Accuracy — Percentage of arrows hit vs. arrows shot.
• Crossbow Accuracy — Percentage of crossbow bolts hit vs. crossbow bolts shot.
• Total Damage Dealt — Cumulative final damage dealt to all entities.
• Total Damage Taken — Cumulative final damage received.
• Highest Single Hit — Records the maximum final damage dealt in a single blow.
• Shield Blocks — Records the number of successful attacks deflected using a shield.

💀 Detailed Death Breakdown

• Deaths by Player — Deaths caused in PvP combat by other players.
• Deaths by Mob — Deaths caused by hostile mobs.
• Deaths by Environment — Deaths caused by natural hazards (lava, fall damage, drowning, void, suffix damage).

🏃 Movement & Physical Activity

• Distance Traveled — Total distance traveled in meters/blocks.
• Jumps — Records the total count of jumps.
• Sneak Time — Total active time spent sneaking.

⛏️ Mining, Progression & Social

• Blocks Broken — Total blocks broken of any type.
• Blocks Placed — Total blocks placed of any type.
• Valuable Ore Tracking — Monitors any block ending in _ORE and Ancient Debris.
• Items Crafted — Total items created through crafting menus.
• Items Enchanted — Total items enchanted (via Enchantment Tables or anvils).
• Mob Kills — Total passive and hostile mobs killed.
• Total Chats — Total count of chat messages sent.
• Average Chat length — Average number of characters per chat message.
• Live Inventory Scan — Invisible, AI-readable scanning of a player's armor and inventory grid (armor, off-hand, and main 9x4 grid).

⚙️ Commands & Permissions

Commands Index

• /aps stats <player> [stat] — View a player's full statistics or query a specific one (e.g. /aps stats Saksh bow_accuracy).
• /aps privacy <feature|all> [on|off] — Manually manage visibility settings for your stats.
• /aps help — Displays the plugin help menu.
• /aps migrate — (Admin Only) Runs the self-healing migration tool to move configuration and player files from v2.x to v3.0.
• /aps <natural language question> — (AI Only) Talk directly to the StatsMaster AI (e.g. /aps compared to Steve, how many diamonds have I mined?).

Permissions Index

• nsr-ai.advancedplayerstats.view — Allows viewing stats (Default: OP).
• nsr-ai.advancedplayerstats.view.inventory — Allows viewing player inventory stats (Default: OP).
• nsr-ai.advancedplayerstats.admin — Access to administrator settings and the migration engine.
• nsr-ai.admin.privacy.bypass — Bypasses privacy restrictions on players' profiles.

🔄 Self-Healing Upgrade & Migration

Upgrading from Advanced Player Stats 2.x is seamless.

1. Place the new Advanced-Player-Stats-3.0.jar in your plugins/ directory.
2. Start the server.
3. Log in as an operator (OP) and run /aps migrate.
4. The migration engine will find your old files under plugins/NSR-AI/addons/NSR-AI-Advanced-Player-Stats, automatically transfer all player statistics and configurations to plugins/Advanced-Player-Stats/, and log the results.

Transforming raw data into intelligent, privacy-respecting gameplay insights.
Developed by BlackForge Studio