[![Godlike Hosting Banner](https://cdn.modrinth.com/data/cached_images/fee3be3d984421f7302741c1cedc0be6ce011469.png)](https://godlike.host/blue_print) 👉 Click the banner or [[start here]](https://godlike.host/blue_print) to get going. Use code BLUE40 and unlock your 40% discount instantly. # Nexa AI (Minecraft Mod + Paper Plugin) > [!NOTE] > This page includes detailed information about the mod/plugin. If it feels too much, you can skip straight to using it. Just install the mod/plugin and run the command `/nexa ` to get started right away. Nexa AI adds an AI agent into Minecraft. * Works as a **Fabric / Forge / NeoForge mod** (clients + servers) * Also available as a **Paper plugin** Players can talk to Nexa in chat and (with the right permissions) let it run server tools like teleporting, locating structures, changing weather/time, and more. ## Features * **Chat with Nexa directly:** `/nexa ` * **Agent Modes:** * **Ask-before-act** (default): Privileged actions are previewed and require confirmation before execution. * **Autonomous**: Nexa can execute allowed steps automatically (guardrails still apply). * **Server Guardrails:** Per-player request limits + global tool cooldown. * **Customization:** Custom assistant name + personality prompt. * **Client GUI:** Open the configuration and chat interface by pressing **`N`** or using the command `/nexa-gui` / `/nex-gui` (Fabric/Forge/NeoForge clients). * **Built-in Tools ("Function Calling"):** Server-aware actions, environment lookups, and screenshot analysis. * **Auto Messages:** Optional greeting on join + occasional idle-time messages (server-wide, can be disabled). * **Update Notifications & Feedback:** Updates checked and feedback sent securely via proxy. --- ## Supported Targets * **Fabric**: Minecraft `26.2` * **Forge**: Minecraft `26.2` * **NeoForge**: Minecraft `26.2` * **Paper**: Minecraft `26.1.2` - `26.2+` *All targets share a common core compiled with Java 25 compatibility.* --- ## Commands ### Chat * `/nexa ` — Chat with Nexa. * `/nexa confirm` — Approve queued actions (ask-before-act mode). * `/nexa cancel` — Cancel queued actions. ### Client GUI * `/nexa-gui` (or `/nex-gui`) — Opens the configuration GUI screen (Fabric, Forge, and NeoForge clients only). ### Configuration (`/nex-config`) * `/nex-config clearchat` — Clear your conversation history. * `/nex-config feedback ` — Send feedback (rate-limited to once per 24 hours). * `/nex-config mode show` — Show your current agent mode. * `/nex-config mode ` — Set your personal agent mode override. * `/nex-config limits status` — Show limits and cooldown. * `/nex-config limits maxrequests <1..15>` — Set max requests per prompt (**requires admin/op privileges**). * `/nex-config limits cooldown ` — Set global tool cooldown (**requires admin/op privileges**). * `/nex-config custom name ` — Change assistant name (**requires admin/op privileges**, max 30 chars / 3 words). * `/nex-config custom prompt ` — Set personality prompt (**requires admin/op privileges**, max 1000 chars). * `/nex-config custom reset` — Reset name/prompt to defaults (**requires admin/op privileges**). * `/nex-config custom show` — View your current custom settings. * `/nex-config automessages enable|disable|status` — Toggle join/idle auto messages (server-wide). ### BYOK (Bring Your Own Key) BYOK is **per-player** and bypasses the default proxy for chat calls. * `/nex-byok status` — Show BYOK status. * `/nex-byok toggle enable|disable` — Enable/disable BYOK. * `/nex-byok provider ` — Choose provider. * `/nex-byok apikey ` — Set API key (required for cloud providers). * `/nex-byok endpoint ` — Set endpoint URL (for local/custom providers, or `default` to reset). * `/nex-byok model ` — Set model name. * `/nex-byok tools enable|disable` — Enable/disable tool calling (mainly useful for local endpoints). * `/nex-byok test` — Test current BYOK config and check connection. --- ## Modes ### **Ask-before-act** Nexa proposes an action preview and waits for confirmation before running any privileged tool. Approve via the clickable buttons in chat (`[Yes]` / `[No]`), or with `/nexa confirm` (deny with `/nexa cancel`). Queue timeout is 30 seconds. ### **Autonomous** Nexa can execute allowed tools without an explicit prompt. Guardrails still apply (cooldowns, request limits, and required privileges). --- ## AI Providers & BYOK Configuration ### **Default AI Service** By default, Nexa uses default services. It is free but you could experience rate limiting, overload, etc. It is recommended to use BYOK for optimal performance. ### **BYOK Mode** BYOK (Bring Your Own Key) lets each player use their own provider + key: * **Google Gemini**: Default endpoint `https://generativelanguage.googleapis.com/v1beta`, default model `gemini-2.5-flash-lite` (supports tool calling). * **OpenAI**: Default endpoint `https://api.openai.com/v1`, default model `gpt-5-chat-latest` (supports tool calling). * **Ollama (Local)**: Default endpoint `http://localhost:11434/v1` (no API key needed, custom models, tool calling toggle). * **LM Studio (Local)**: Default endpoint `http://localhost:1234/v1` (no API key needed, custom models, supports tool calling). * **Custom**: Full OpenAI-compatible custom endpoint, custom models (supports tool calling). *Note: BYOK settings (including API keys) are stored securely on the server in the world data file.* --- ## Nexa Tools (Function Calling) Nexa can call built-in tools depending on player permissions: ### **Unprivileged Tools** (Available to all players) * `getPlayerState`: Get current player details (position, health, gamemode, dimension, difficulty, last death location). * `getInventorySummary`: Inspect the contents of your inventory, main/off-hand items, and armor. * `getEnvironmentInfo`: Retrieve current environment conditions (time, weather, biome, facing direction, difficulty, dimension). * `getGameRules`: Read the value of server game rules (e.g., `keepInventory`, `doDaylightCycle`). * `getNearbyEntities`: Scan for entities (mobs, players) within a 48-block radius. * `saveLocation`: Save your current coordinates as a custom named location. * `removeLocation`: Remove a saved location or clear all saved locations. * `listSavedLocations`: View all your saved locations and their coordinates. * `getAgentContext`: Review Nexa's current operational mode, server defaults, guardrails, and permission privileges. * `analyzeScreenshot`: Capture a screenshot of the client's screen to visually analyze the game state (available when mod is installed client-side). ### **Privileged Tools** (Require `nexa.admin` / OP status) * `locate` (executes immediately even in ask-before-act): Find coordinates of structures (e.g., village) or biomes. * `teleport` (queued in ask-before-act): Teleport to specific coordinates. * `timeSet` (queued in ask-before-act): Set the server time (preset like day/noon/night/midnight or a numeric tick value). * `weather` (queued in ask-before-act): Change the server weather (clear, rain, thunder) and specify duration. * `giveEffect` (queued in ask-before-act): Apply status effects with customizable duration, amplifier, and particles. * `spawnEntity` (queued in ask-before-act): Spawn a specific entity (pig, zombie, etc.) at your location or specified coordinates (max 20 entities). --- ## Permissions & Privileges Nexa integrates with **LuckPerms** for granular permission control across Fabric, Forge, NeoForge, and Paper. ### **Permission Nodes** * `nexa.use` — Access to `/nexa`, `/nex-config`, `/nex-byok`, and `/nexa-gui` (Default: allowed for all players). * `nexa.admin` — Administrative actions (limits/cooldown modification, custom prompts, privileged tools, server-wide changes). ### **Vanilla Fallback (Without LuckPerms)** * `nexa.use` is allowed for everyone. * `nexa.admin` falls back to OP / Gamemaster privileges on dedicated servers, and Creative Mode in singleplayer. --- ## Requirements & Installation ### Java * Minecraft **26.2**: Typically runs on **Java 25**. ### Installation * **Fabric**: Install Fabric Loader + **Fabric API**, then drop the `nexa-fabric*.jar` into `.minecraft/mods/` * **Forge**: Drop the `nexa-forge*.jar` into `.minecraft/mods/` * **NeoForge**: Drop the `nexa-neoforge*.jar` into `.minecraft/mods/` * **Paper**: Drop the `nexa-paper*.jar` into `plugins/` and restart the server. *Tip: Server-side features work with only the server jar installed. Install the client mod to enable the GUI (keybinding **`N`**) and screenshot analysis.* --- ## Guardrails (Server) * Agent mode: `ASK_BEFORE_ACT` or `AUTONOMOUS` * Per-prompt request budget (`maxrequests`) and a global cooldown (`cooldown`) * Privileged actions are previewed (and can be denied) in ask-before-act mode. --- ## Fair Use, Safety, and Privacy * **Community Built**: Please don’t abuse default services (rate limits/guardrails exist for a reason). * **AI Provider Terms**: Default service prompts/responses are processed by Google Gemini. When using BYOK, your chosen provider's terms apply. * **Data & Security**: Settings and BYOK API keys are saved per-world in `chatmc_locations.json`. Only grant server file access to trusted individuals. * **Feedback**: Feedback messages submitted via `/nex-config feedback` are sent to the proxy with identifying metadata. --- ## Support & Contributions If you encounter issues, have feedback, or wish to contribute, please join our Discord server. **Discord:** [https://discord.gg/Wvst4znsgk](https://discord.gg/Wvst4znsgk)

Mod_MC