mc_aiplayer

The LLM chooses intent. Goals define completion. Deterministic tasks execute.

What AIBot is

AIBot is an open-source server-side Fabric mod for Minecraft 1.21.3. It creates a real server-side player, accepts natural-language instructions, and maps them onto deterministic game logic for mining, crafting, smelting, building, farming, combat, fishing, trading, storage, and survival.

The model is not allowed to improvise per-tick movement or edit the world directly. It chooses from a registry of 63 tools; the goal engine and 34 concrete Task state machines own execution. The codebase currently contains 9 typed Goal variants, 197 main Java classes, and about 32K lines of main Java.

This is an active engineering project, not a claim that every goal succeeds on every terrain. Long navigation, deep mining, large stockpiles, and full structure completion still need broader clean-commit, multi-seed evidence.

Operating profiles

New installations default to strict_survival. The profile is resolved once at startup and is shown in structured logs and the in-game control panel together with the effective privileged capabilities.

An existing legacy aibot.json with no top-level profile is loaded as operator once for compatibility and emits a migration warning. A missing profile on a new install defaults to strict. Invalid file or AIBOT_PROFILE values fail closed to strict_survival.

See Operating profiles for the full matrix and migration rules.

Architecture

flowchart TB
    U["Player: chat, command, or Bob panel"] --> B["Brain: OpenAI-compatible tool calls"]
    B --> G["Typed Goal + GoalPlanner"]
    G --> E["GoalExecutor + postcondition"]
    E --> T["34 deterministic Task state machines"]
    T --> A["Actions + A* navigation"]
    A --> W["Minecraft server world"]
    W --> P["Visible perception"]
    P --> B
    S["Safety, pause/resume, authorization, lifecycle"] -. guards .-> E
    S -. guards .-> T
    R["Versioned runtime snapshot"] -. restores .-> E

The nine Goal variants cover item acquisition, pickaxe tiers, ore, crops, armor, workstations, stockpiles, food, and blueprint builds. Goal completion is evaluated as a typed postcondition, so a Task ending is not automatically treated as mission success.

Runtime control supports cancel/replace and nested pause/resume. Bot, mission, checkpoint, and shared-job state is written through a versioned atomic snapshot. Restart restoration reopens stale job leases instead of trusting an old process owner.

Current verification status

The repository separates source-level checks, world-backed tests, diagnostic evidence, and release evidence:

The production mod does not contain /aibot test or /aibot verify. Those commands live only under src/gametest and are available through runHarnessServer, keeping test-only controls out of production jars.

See Testing and evidence and the generated capability matrix.

Quick start

Requirements

Build and run

git clone https://github.com/zoyluoblue/mc_aiplayer.git
cd mc_aiplayer

./gradlew build
./gradlew runServer
./gradlew runClient

Configure the model and profile

The recommended way to provide the default DeepSeek key is an environment variable:

export DEEPSEEK_API_KEY="sk-your-key"

On first run, AIBot writes aibot.json to the Fabric config directory. A minimal explicit strict configuration is:

{
  "profile": "strict_survival",
  "operatorCapabilities": {
    "hiddenBlockScan": false,
    "emergencyTeleport": false,
    "forcedPickup": false,
    "manualTeleport": false
  },
  "deepseek": {
    "baseUrl": "https://api.deepseek.com",
    "model": "deepseek-chat"
  }
}

Any OpenAI-compatible chat/tool-calling endpoint can be used by changing baseUrl and model. AIBOT_PROFILE=strict_survival or AIBOT_PROFILE=operator overrides the file for one process.

Usage

/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 Bob

Press Alt + 0 to open the Bob panel. It shows health, hunger, current work, model usage, inventory, operating profile, and effective privileged capabilities. Manual teleport controls are disabled unless MANUAL_TELEPORT is effective.

Commands, panel/network actions, chat routing, tools, and shared jobs pass through owner/operator authorization checks. Run AIBot only on servers where the owner has approved the selected profile and capabilities.

Tests and evidence

./gradlew test
./gradlew runGameTest
bash scripts/persistence_restart_test.sh

Start the test-only interactive server when you need /aibot test or /aibot verify:

./gradlew runHarnessServer

Create one isolated runtime evidence bundle:

bash scripts/evidence_run.sh \
  --scenario capability_profile+runtime_control_suite \
  --profile strict_survival

Outputs are immutable directories under artifacts/evidence/<run-id>/. A dirty worktree, fixture log, unstable revision, missing actual-seed proof, or other provenance gap produces UNVERIFIED, even when the scenario itself passes.

bash scripts/evidence_validate.sh artifacts/evidence/<run-id>
bash scripts/evidence_validate.sh --require-verified artifacts/evidence/<run-id>

reports/baselines/index.tsv is the only selector for new VERIFIED capability baselines. scripts/pin_baseline.sh requires an explicit capability ID and run directory; it never searches for the newest or best result. The older reports/capability_baseline_manifest.tsv remains a capability registry and legacy fallback, whose old reports stay UNVERIFIED.

Project structure

src/main/java/io/github/zoyluo/aibot
├── action/        # movement, mining, interaction, inventory, building
├── brain/         # LLM requests, tools, authorization-aware dispatch
├── command/       # production /aibot commands
├── coordination/  # shared jobs and idle coordination
├── goal/          # typed goals, planner, executor, postconditions
├── mode/          # strict/operator capability policy
├── persist/       # versioned runtime snapshot and atomic storage
├── task/          # deterministic Task state machines and safety layers
└── …              # entity · mining · network · observe · pathfinding

src/gametest/      # GameTests and test-only /aibot test + /aibot verify

Known limits

• Real-terrain success rates in the capability matrix are historical legacy diagnostics until replaced by pinned VERIFIED bundles.
• Strict mode is intentionally less forgiving: a denied privileged recovery may turn an unsafe route into a clean failure instead of teleporting the bot.
• Long-distance navigation, zero-to-diamond runs, 100-item bulk mining, and complete structure validation are not release-certified.
• LLM-backed story tests are opt-in and billed. Normal CI and nightly deterministic jobs do not receive DEEPSEEK_API_KEY.

See the