AIBot for Minecraft
A real server-side player that carries out Minecraft survival goals from natural-language instructions.
Per-dimension scores and reasoning
The default strict_survival profile, granular capability flags, fail-closed configuration, owner/operator authorization, and read-only CI permissions provide strong least-privilege evidence. The billed LLM workflow requires explicit confirmation, but ordinary mining, building, and combat effects are not shown with per-action previews or confirmations, so confirmation is not comprehensive. The README identifies the external LLM endpoint, model configuration, and world-execution path, but does not fully enumerate transmitted context, log retention, or privacy boundaries. Keys are supplied through environment variables and GitHub Secrets, and normal CI receives no key; however, local secret protection, log redaction, and rotation are undocumented. Dependencies and CI versions are explicit, but no dependency integrity policy, vulnerability scanning, or vulnerability-response evidence is shown. World effects are authorization- and profile-gated, with cancel and pause controls, but completed world mutations have no documented transactional undo. License, author attribution, and acknowledgements for Fabric, DeepSeek, and the Carpet tradition are clear.
The README, architecture, test inventory, and workflows consistently describe the Java, Minecraft, Fabric, profile, and verification model, while candidly separating verified from unverified evidence. Required dependencies and build commands are clear, but retry, backoff, fallback, or degraded operation for an unavailable external model service are not evidenced. Migration warnings, fail-closed configuration, and CI input errors are useful, yet no comprehensive user-facing taxonomy or recovery guidance is shown for runtime navigation, task, network, or model failures.
The documentation serves players, server operators, contributors, and both English and Chinese audiences, with scenarios spanning mining, building, farming, and combat. Nine Goal variants, 63 tools, 34 task state machines, and strict/operator policy clearly bound capabilities. Command examples and typed goals support precise invocation, but the supplied files do not contain a complete supported-utterance reference, ambiguity policy, or tool-selection specification, so trigger precision is not full. Minecraft, Fabric, Java, API compatibility, environment overrides, and legacy-config migration are documented thoroughly.
The README has strong organization across quick start, architecture, usage, verification, structure, and limitations, and its installation requirements and commands are directly actionable. AIBot, Bob, configuration, command, and profile naming remain consistent. Several command and configuration examples are present, but there is no dedicated FAQ or systematic troubleshooting guide. Known limitations are concrete and resist overclaiming. The complete MIT license matches the metadata. No release-version policy, tag scheme, or changelog is supplied, leaving version/change management thin. An account attribution and general contribution process are present, but maintainer roles, support channels, and response expectations are unspecified; unknown publisher identity is not itself treated as suspicious.
Chat, commands, a control panel, structured logs, status inspection, and persistent restoration make outcomes observable, controllable, and reusable. A real server-side player driven through typed goals and deterministic state machines offers clear marginal value over a Python harness or simple chat interface. Billed stories require confirmation, ordinary CI avoids secret use, and the panel reports model usage; however, token or monetary budgets, spending caps, caching, and server-resource estimates are absent, limiting the cost-benefit score.
Claims are tied to concrete counts, test layers, script names, evidence directories, validators, and baseline-selection procedures, providing strong traceability. README assertions about tests and persistence are corroborated by matching CI commands, while billed LLM behavior is supported by a separate workflow. The material explicitly distinguishes source checks, current CI, dirty-worktree local results, historical diagnostics, and release evidence, and it labels uncertified capabilities candidly. This remains a static assessment of the supplied files; no command was executed.
- Enabling the operator profile or all operatorCapabilities permits hidden-block scans, emergency teleportation, forced pickup, and manual teleportation; use it only with explicit server-owner approval.
- Natural-language tasks can mutate a persistent game world, while the supplied material shows no general undo for completed mining, building, or inventory effects; validate first in a backed-up world or constrained area.
- LLM requests go to DeepSeek or a configured OpenAI-compatible endpoint, but the supplied material does not fully specify transmitted fields, retention, or privacy policy; avoid placing sensitive information in prompts or visible game context.
- This assessment did not execute the build, tests, or runtime scenarios; reported counts, passes, and safety properties were evaluated only as static source claims.
- No dependency vulnerability scan, secret-rotation process, spending cap, or degraded-mode policy for model-service outages is shown; operators should add those controls.
What does this agent do, and when should you use it?
AIBot is a server-side Fabric mod for Minecraft 1.21.3 that creates a real server player and accepts supported goals in English or Chinese. Its Brain calls DeepSeek or another OpenAI-compatible chat and tool-calling endpoint, selecting intent from a registry of 63 tools. `GoalPlanner`, `GoalExecutor`, nine typed Goal variants, and 34 deterministic Task state machines plan, execute, and verify the work instead of giving the model per-tick movement or direct world-editing control. It covers mining, crafting, smelting, building, farming, combat, fishing, trading, storage, and survival through chat, `/aibot` commands, and the Bob control panel. Versioned atomic snapshots preserve bot, mission, checkpoint, pause, and shared-job state across restarts. It is best suited to users prepared to operate a Minecraft/Fabric server and evaluate reliability for their own terrain, since several long or complex scenarios lack release-grade evidence.
A player submits a goal through chat, /aibot brain say, /aibot task assign, or the Bob panel. The Brain sends visible-world context to an OpenAI-compatible chat and tool-calling endpoint and selects an intent from 63 registered tools; GoalPlanner maps that intent to a typed Goal, while GoalExecutor evaluates its postcondition. The 34 Task state machines then use the action layer and A* navigation to perform movement, mining, interaction, inventory handling, building, and related operations. Outputs are in-world results such as acquired items, crops, food, armor, workstations, stockpiles, or blueprint builds, plus recorded model usage and runtime state. Safety, lifecycle, and authorization checks guard commands, panel and network actions, chat routing, tools, and shared jobs. Atomic snapshots retain missions, checkpoints, queues, pause state, and Job claims; restart restoration reopens stale leases before work resumes.
- A private Minecraft server owner wants a real server-side player to carry out requests such as “mine 3 diamonds.”
- A Fabric developer wants to study a game-agent design where an LLM chooses intent and deterministic state machines control execution.
- An English- or Chinese-speaking player wants to assign mining, crafting, farming, combat, fishing, building, or storage work through chat, commands, or a control panel.
- A server administrator wants survival-oriented automation with hidden-block scans, emergency teleport, forced pickup, and manual teleport disabled under
strict_survival. - A maintainer wants JUnit, Fabric GameTest, a two-JVM restart probe, and evidence scripts for checking policy, persistence, runtime controls, and world-backed behavior.
What are this agent's strengths and limitations?
- The model selects intent from 63 tools while 34 deterministic Task state machines perform execution, avoiding unrestricted per-tick LLM control.
- It creates a real server-spawned player and does not require a Mineflayer account or Python control harness.
strict_survivaldisables hidden-block scanning, emergency teleport, forced pickup, and manual teleport while filtering resource and entity queries through nearby visibility.- Runtime controls include cancel or replace, nested pause and resume, and restoration from a versioned atomic snapshot.
- The model layer supports configurable OpenAI-compatible chat and tool-calling endpoints through
baseUrlandmodel.
- Deployment is tied to Minecraft 1.21.3, Fabric, and Java 21 and requires operating a server build.
- Model-backed operation needs network access and an API credential; opt-in LLM story tests are billed.
- Long-distance navigation, zero-to-diamond runs, 100-item bulk mining, and complete structure validation are not release-certified.
- Existing real-terrain capability reports are mostly historical diagnostics, and locally passing runs from a dirty worktree are labeled
UNVERIFIEDrather than proof of the current HEAD. - Strict mode can turn an unsafe route into a clean failure when privileged recovery is denied, and success is not guaranteed across terrain.
- A legacy
aibot.jsonwithout a top-levelprofileloads once asoperatorfor compatibility, so adopters must review migration warnings and capability settings.
How do you install or deploy this agent?
Requirements are Minecraft 1.21.3, Fabric Loader 0.18.4+, Fabric API 0.114.1+1.21.3, Yarn mappings 1.21.3+build.2, and Java 21.
Run:
git clone https://github.com/zoyluoblue/mc_aiplayer.git
cd mc_aiplayer
./gradlew build
./gradlew runServerUse ./gradlew runClient when a client environment is needed. Supply the default DeepSeek credential with export DEEPSEEK_API_KEY="sk-your-key". On first launch, AIBot creates aibot.json in the Fabric configuration directory and defaults new installations to strict_survival. To use another OpenAI-compatible chat and tool-calling service, change deepseek.baseUrl and deepseek.model in that file. AIBOT_PROFILE=strict_survival or AIBOT_PROFILE=operator can override the file for one process.
How do you use this agent?
After starting the server and configuring a model, try:
/aibot spawn Bob
/aibot list
/aibot brain say Bob mine 3 diamonds
/aibot task assign Bob mine minecraft:stone 16
/aibot task status Bob
/aibot brain status BobPress Alt + 0 to open the Bob panel, which displays health, hunger, current work, model usage, inventory, operating profile, and effective privileged capabilities. Manual teleport controls remain disabled unless MANUAL_TELEPORT is effective. The production mod does not include /aibot test or /aibot verify; start ./gradlew runHarnessServer when those test-only commands are required.
How does this agent compare with similar options?
Unlike a Mineflayer bot account or a Python-driven control harness, AIBot runs as a Fabric server mod and creates a real server-side player. It also avoids direct per-tick LLM control and world editing: the model selects intent, typed Goals define completion, and deterministic Task state machines execute the plan. Its fake-player model follows the Carpet-mod tradition, although the source provides no feature or performance benchmark against Carpet.
FAQ
Is DeepSeek mandatory?
baseUrl and model can point to another OpenAI-compatible endpoint that supports chat and tool calling.Does it teleport or scan hidden blocks by default?
strict_survival, which disables hidden-block scans, emergency teleport, forced pickup, and manual teleport. Operator capabilities can also be disabled individually.