Settings

Settings

All of Blockpal's options are changed in the in-game panel. As of 3.4.0 there are no per-setting commands (/ai settings, /ai token, /ai listen, /ai active, /ai commands were removed) — everything lives in the panel, which writes to config/blockpal/config.json.

Operator-only. Server-wide settings are admin-gated (adminPermissionLevel, default 2 = ops). The owner of a singleplayer/LAN world always counts as an admin (3.16.1) — even with cheats off — so you can always configure your own world. Players can always change their own model and key (see Per-Player Keys & Models). See also Security.

Opening the panel

/ai panel (or /ai menu), or — unless disabled — sneak-right-click your assistant. Every Blockpal screen has a shared tab bar at the top to move between the panels:

Tab	Who	What's there
Settings	admins	The five sub-tabs below (names, AI, behaviour, combat, developer)
Admin	ops	Server controls + stats — see Admin Menu
My Settings	everyone	Your own model and API key

Settings sub-tabs

Sub-tab	What's here
Identity	Name, skin, Open skins folder button, Default personality
Behavior	Chat listening, active analysis, sneak-to-open-menu, allow custom personalities, allow possession mode, allow agent voice, thinking style, send pictures to the AI, live on its own, creative-mode warning, do things by hand, human-like pauses, eyesight (picture size + view distance + script time limit), Growth village sizes, follow distance, guard radius, performance preset
AI & API	The one AI connection, MCP server settings + Open setup guide button, API provider preset, API URL, model, token, temperature, max tokens, and the endpoints for Ollama, the Player2 app and the free service
Combat	Allow commands, permission level, flee health
Developer	Action tick delay, task watchdog timeout, flee health (high-risk — see Developer Menu)

• Each setting has a hover tooltip explaining it.
• Edits are held in a draft and captured on each tab switch, so moving between tabs doesn't lose changes.

Personality: the Identity tab sets the default personality for newly summoned bots, and the Behavior tab has an Allow custom personalities toggle. Each player changes their own bot's personality with /ai personality <id> / /ai personality custom <text> or the My Settings screen (/ai mymenu). See Personalities.

• Save / Apply / Cancel bar is pinned at the bottom; Esc auto-saves.
• The token field stays blank when one is set — leave it blank to keep the current token, or type a new one to replace it.
• Password-style masking (3.17.2) — the token box shows dots (•••) by default and is read-only until you press the Show key toggle beneath it, which switches it to an editable plaintext box for typing/pasting your key; toggle it off again to re-mask (what you typed is kept, just hidden — no need to retype it). This only ever affects text you're actively entering — an already-saved key is still never sent back to the menu at all (see API token security below). The same masking + Show key toggle is on the personal key box in My Settings (/ai mymenu).

One AI connection at a time (3.25.0)

The AI & API tab starts with a single AI connection picker, and that is the whole answer to "what is thinking for my bots":

Connection	What it means
MCP server	An AI app you already use (Claude, ChatGPT, Grok, Gemini) connects to your world and drives the bot. No key stored in the game — see MCP server
My own API key	An OpenAI-compatible key + model you type in below
Player2 app	The free Player2 app, or its cloud with a PLAYER2_KEY
Local Ollama / LM Studio	Your own model on your own machine — no key, no internet
Free keyless service	A small free internet model. Works out of the box, rate-limited
No AI	Companions still eat, fight and survive — they just don't think with a model

Choosing one turns the others off. Before 3.25.0 a key, Player2, Ollama and the free service could all be "enabled" at once and a hidden priority order decided which answered — so nobody could tell which AI was really running, or which one was being billed. Now there's one setting and one answer. A live line under the picker names it outright: "▶ Bots will use: …".

By command: /ai connection shows it, /ai connection set <mcp|key|player2|ollama|free|off> changes it (ops). Setting a shared key with /ai admin token also switches the connection to My own API key, since that's obviously what you meant.

Existing servers are migrated: whatever your old settings would have resolved to becomes your connection, so nothing changes on upgrade.

How companions think (3.25.0)

On Settings → Behavior:

Setting	Default	Effect
Thinking style	Look and write code	The bot looks at the world, gets a picture of what its eyes see, and writes a script that presses its keys. Switch to Classic action plan (JSON) for the pre-3.25 planner
Send pictures to the AI	on	Off = the written scene only — cheaper, and needed for models that can't see images
Live on its own	on	Keep-alive reflexes that need no AI at all: eat, escape water/fire, unstick, walk back to you
Warn me in creative mode	on	Companions never teleport, so a flying owner leaves one behind

And under Its eyesight on the same tab: picture width, picture height, how far it can see, and the script time limit. Bigger pictures are sharper but cost one ray cast per pixel each time the bot looks, so the sliders are capped at sensible values.

Full explanation and the scripting language: Vision & Code.

Everything is in the panel now (3.25.1)

Settings that previously existed only in config.json or behind an /ai admin command have visual controls: the vision size and range, the script time limit, do things by hand and human-like pauses, the Growth village population numbers, and the endpoint boxes for the Player2 app and the free keyless service. The /ai admin … text commands still work and remain the way to configure from a Bedrock or vanilla client with no GUI.

The three list settings — the allowed-model list, the bring-your-own-key exemption list, and the Ollama model pool — are still managed with commands (/ai admin models|keylist|ollama models add|remove|list), since they're add/remove lists rather than single values.

Local AI on this machine (3.27.0)

Settings → AI & API → Local AI on this machine. Blockpal downloads a model (under 3 GB) and runs it on your graphics card — the keyless option, replacing the old free internet service.

Setting	Default	What it does
localModelId	qwen3b	Which model to run
localAutoStart	on	Start it with the server, once downloaded
localContext	4096	Context window in tokens
localGpuLayers	-1	Layers on the GPU; -1 lets llama.cpp decide
localPort	8081	Loopback port; never exposed off the machine

Consent is not a setting. The panel changes every value above but cannot agree to a download — a settings packet claiming consent is ignored. Agreeing happens at the /ai local setup prompt that shows you the size. See Local AI on your GPU.

How fast it acts, and how it fights (3.26.0)

On Settings → Behavior:

Setting	Default	What it does
reactionSpeed	fast	One setting for every pause the mod adds — step delay, head-turn rate, how often it re-thinks, vision rate, script budget. instant / fast / human.
combatSkill	skilled	basic (walk in and swing), skilled (range, circling, shield, disengage), expert (crits, bow).
allowPvp	off	May a companion fight a player at all. Even on, provoked-only and never the owner or anyone trusted.

actionTickDelay still exists on the Developer tab but is now a floor: raise it above 2 deliberately and it is honoured, otherwise reactionSpeed decides. See Speed & Combat.

Learning by watching — PVT (3.26.0)

Also on Settings → Behavior. pvtEnabled, pvtAutoRecord, pvtConfidence, pvtHiddenSize, pvtEpochs, pvtLearningRate, pvtMaxFrames. Recording is opt-in per player and never enabled by a setting — see PVT — learning by watching.

The Thinking style cycler gains a third option, "Act on what it learned by watching" (aiLogicMode = pvt).

AI provider presets (3.24.0)

Blockpal talks to any OpenAI-compatible chat-completions endpoint, so switching "which AI you use" is really just swapping the API URL and a matching model. The AI provider cycler at the top of the AI & API tab does both in one click:

Provider	Endpoint	Default model	Key
HuggingFace	router.huggingface.co/v1/chat/completions	mistralai/Mistral-7B-Instruct-v0.2	your HF token
ChatGPT (OpenAI)	api.openai.com/v1/chat/completions	gpt-4o-mini	ships with a public demo key
Claude (Anthropic)	api.anthropic.com/v1/chat/completions	claude-3-5-sonnet-20241022	your Anthropic key
Gemini (Google)	generativelanguage.googleapis.com/v1beta/openai/chat/completions	gemini-2.0-flash	your Google API key
Grok (xAI)	api.x.ai/v1/chat/completions	grok-2-latest	your xAI key

• Picking a provider fills the API URL and Model boxes for you. For ChatGPT it also reveals and pre-fills a public demo key so it isn't blank the first time (that key is probably rate-limited or dead — replace it with your own OpenAI key via Show key or /ai mykey <key> for real use).
• Every other provider needs your own API key for that service — set it in the token box (press Show key first) or with /ai admin token <key> / /ai mykey <key>.
• If the API URL matches none of the presets the cycler reads Custom — you can still point at any other OpenAI-compatible endpoint (a local Ollama/LM Studio, OpenRouter, …) by editing the URL by hand.
• Bedrock / vanilla / no GUI: /ai admin provider <name> where <name> is huggingface, chatgpt, claude, gemini or grok (bare /ai admin provider lists them and shows the current one).

The free AI fallback (3.17.0)

Blockpal works with no API key at all: when no key resolves for a request (no shared server key, no personal key), it automatically falls back to a free, keyless OpenAI-compatible service (Pollinations) so the companion can plan and act out of the box. HuggingFace stays the configured default — the moment a token is set it always wins, and the free service is only ever the no-key fallback.

• Free AI fallback toggle (AI & API tab, default on): turn it off to make a real key strictly required again — with it off and no key, the AI can't run.
• freeApiUrl / freeModel in config.json point the fallback anywhere else (e.g. a local keyless Ollama) — there are deliberately no GUI fields for these.
• The free service is a shared public endpoint: expect it to be slower and lower quality than a keyed model, and don't send anything sensitive through it.
• The AI & API tab's status line tells you which mode you're in ("bots run on the free built-in AI" vs "API key saved").

Admin options (in the Admin panel)

Ops change these right in the Admin tab — click a toggle or a level cycler, no commands needed:

Option	Meaning
Allow commands	Let bots run /setblock, /fill, /give, etc.
Command perm level	Permission tier (0–4) for those commands (2 = command-block)
Admin level	Op tier (0–4) needed to change settings / use the admin panel. Default 2
Max bots	Most bots allowed on the server at once (0 = unlimited). Default 8
Require own API key	Players must bring their own key (except the whitelist)
Players may pick model	Allow players to choose their bot's model
Allow possession mode	Let players hand their character to their companion (/ai possess) — see Possession Mode

The two lists — the allowed models and the own-key whitelist — are managed with /ai admin models … and /ai admin keylist … (see Per-Player Keys & Models).

API token security

The token is never shown back, never logged, and stored obfuscated in config.json (hfTokenObf) rather than as plain text. For the strongest protection, set it via the BLOCKPAL_API_TOKEN environment variable instead — then it's used but never written to disk. On a vanilla-client server with no GUI, this env var (or hand-editing config.json) is how you set the shared key. Full details in Security.

Persistence & versioning

Settings live in config/blockpal/config.json. The file carries a configVersion stamp:

• Missing or corrupt → regenerated from defaults (and a fresh install kicks off the first-run tutorial).
• From an older mod version → newly-added fields are filled with their intended defaults (not Java's false/0), while existing values like your API key are preserved.

So your API key carries across mod updates, and a deleted file just comes back as defaults.

Schema v12 (3.25.0) added the exclusive aiConnection, the MCP server settings (mcpPort, mcpAllowRemote, mcpRequireToken, mcpTokenObf), the vision/code brain (aiLogicMode, visionEnabled, visionWidth, visionHeight, visionRange, scriptMaxTicks), survivalBrain and creativeModeWarning. Upgrading servers keep the provider they were already using. allowBotTeleport appears in the file as false and is deliberately not editable — companions never teleport.

Saves are crash-safe (3.17.0). The config is serialized fully in memory, written to a temp file, and atomically moved over config.json, so a crash, full disk or antivirus interruption can never leave a half-written settings file. The previous good file is kept alongside as config.json.prev for hand recovery, and a transient write failure (e.g. a virus scanner briefly locking the file) is retried automatically. Failures are never silent — the in-game save message shows the real config path and turns red if the write failed.