Home

Welcome to the Blockpal Wiki

Blockpal is a Minecraft Fabric mod that drops a friendly AI companion entity (default name Ethan) into your world. It reads your chat, plans multi-step tasks through a language model, fights back on reflex, manages its own inventory and gear, and configures itself from a real in-game settings screen.

Blockpal was previously released as Nexus AI. As of 3.0.0 everything was renamed: the mod id is now blockpal, the texture namespace is blockpal:, and settings live in config/blockpal/. Configs and skins from older ai-assistant builds are not carried over — set 3.0.0 up fresh.

New here? Start with these

1. Quick Start — up and running in under a minute.
2. Installation — download the jar (or build it), install Fabric.
3. Getting Started — summon Ethan and add an AI token.
4. Talking to Your Assistant — just type in chat.

What it can do

• Connect the AI you already pay for — Blockpal runs an MCP server, so Claude, ChatGPT, Grok or Gemini can connect straight to your world and drive the companion. No API key stored in the game. It's the easiest way to give it a brain.
• It looks, then writes code — the companion sees a picture rendered from its own eyes, decides, and writes a little script that presses its movement keys and mouse buttons. Slower and clumsier than magic on purpose: everything it does, a player could do. See Vision & Code.
• It can run entirely on your own machine — Blockpal downloads a small model (under 3 GB) and runs it on your graphics card. Free, private, offline, no key. It asks before downloading anything. See Local AI on your GPU.
• It learns by watching you play — let it watch (/ai pvt watch on, off by default) and it learns to move and react from your own play, with no model call at all. Reflexes from what it learned, intent from the model. See PVT — learning by watching.
• It's quick, and it can fight — one reactionSpeed setting replaced a dozen invented delays, and it now holds a range, circles, shields, times crits and backs off when losing. See Speed & Combat.
• It uses chests — opens chests, barrels, shulkers and furnaces within arm's reach, takes and stores stacks, loads ore and fuel into the right furnace slots.
• It never teleports — companions walk, swim and climb after you like something that actually lives in the world. (You'll get a warning the first time you go creative.)
• It lives on its own — with no AI connected at all it still eats when hurt, swims up when drowning, gets out of fires and makes its own way back to you.
• Named companion — spawns as Ethan with a live nametag; rename any time.
• Reads the room — active analysis runs chat through an LLM so "can you clear these trees?" just works, no command words needed.
• AI-planned tasks — natural-language requests become something it goes and does (the classic JSON planner is still available as a setting).
• Instant quick-commands — come / follow / stay / stop / where are you, no token needed.
• Always reacting — combat and retreat run on an instant reflex layer in every mode, with no API call; planning is fully async.
• Runs commands — /setblock, /fill, /give, /summon, /clone, /effect… safely gated. See Running Commands.
• Inventory & gear — picks up drops, auto-equips the best weapon/armor, eats food.
• Custom skins — built-in palettes or your own PNG. See Custom Skins.
• Personalities — pick how it talks & acts: friendly, cheerful, grumpy, stoic, heroic, shy. See Personalities.
• Possession mode — hand your own character to your companion and let the AI drive you from a typed console. See Possession Mode.
• Voice — hold V and talk to your companion (Whisper transcription), and hear it answer out loud — privately, unless you share; linked agents take turns speaking, never interrupting. See Voice.
• Trust & per-bot management — own several companions, set each up differently, and trust friends to command a specific one. See Trust & Per-Bot Management.
• Emergency FPS kill-switch — auto-disables the mod if framerate collapses.
• Admin menu (ops) — manage/kill all bots, set a bot cap, and see live stats (bots, players, FPS). See Admin Menu.
• Locked-down config & key protection — only operators can change server-wide settings; your API key is obfuscated at rest and can live in an env var. See Security.
• Works in every gamemode — survival, adventure and creative.
• Bedrock-friendly — friends on iPad/console/phone can join and play with Ethan through a Geyser proxy; no client mod needed on Bedrock.
• Native Bedrock Add-On — a from-scratch recreation for Bedrock Edition puts the companion in your own single-player Bedrock world (offline planner, personalities, chat commands — no server needed). See Bedrock Add-On.
• One-click hosting — a Java player can download & launch a Bedrock-ready server (Minecraft + Fabric + the latest Geyser & Floodgate) from the pause menu or /aihost. See Bedrock (Geyser).

Full page index

Page	What's on it
Installation	Download, install, version compatibility
Getting Started	First summon, AI token setup
Commands	Every /ai command
Talking to Your Assistant	Chat, quick intents, addressing by name
Possession Mode	Let your companion drive your own character from a typed console
Voice	Hold V to talk to your agent; it talks back — private, shareable, linked agents take turns
Client-Side Assistant	Private chat box, tips & off-server possession — works on any server
Settings	The in-game settings panel (no more setting commands)
Performance Presets	Normal / Opus / Potato
Custom Skins	Built-in and drop-in skins
Personalities	How your companion talks & acts
Trust & Per-Bot Management	Own several bots; let friends command one
Running Commands	Command execution, permission levels, denylist
AI Actions	The 16 action types the planner can use
Bedrock (Geyser)	Let Bedrock players join via Geyser & Floodgate, plus one-click "Host with Blockpal"
Bedrock Add-On	The native Bedrock Edition recreation — AI companion in a single-player Bedrock world
Friend Sharing	Host, invite (Java + Bedrock), and share control of your bot
Minigames	Play game modes with the bot & friends — Chained, Same Health, One Block, Fusion (in development)
Per-Player Keys & Models	Bring-your-own-key, exemptions, selectable models
Admin Menu	Ops-only panel: manage/kill all bots, bot cap, live stats
Security	Permission gating, API-key protection, what .gitignore can't do
Terms & Policy	Fair-use / no-cheating policy and disclaimers
Developer Menu	What every high-risk developer setting does
More Info	How it works, architecture, changelog, precautions
Troubleshooting	Fixes for common problems
Building From Source	Gradle / Loom build docs
FAQ	Quick answers