Architecture en

Architecture

One core principle: the LLM plans, deterministic tasks execute.

AIBot deliberately stitches together a "flexible but unreliable" language model with a "reliable but rigid" deterministic engine, taking the best of both.

Overview

flowchart TB
    P["🎮 Player — natural language · /aibot · Bob panel"] --> B
    subgraph COG["Cognition & Decision"]
      B["🧠 Brain · DeepSeek LLM<br/>56 tools"] --> G["🎯 GoalPlanner<br/>backward-chaining"]
      G --> E["⚙️ GoalExecutor<br/>step state machine"]
    end
    E --> T["🔧 Task FSM ×44<br/>mine · smelt · craft · combat · farm · build …"]
    T --> A["🛠️ Action primitives + A* pathfinding"]
    A --> W["🌍 Minecraft world · Fabric 1.21.3"]
    W -->|perception| B
    S["🛡️ Safety net · every tick<br/>NavSafety → Stuck → Danger → Idle"] -. guards .-> T

Loading

Layers

Layer	Package	Role
Perception	perception · observe	Compress world state into a structured snapshot for the brain
Brain	brain	DeepSeek tool-calling loop; intent → goals / actions. See [[Brain & Tools
Goal engine	goal	Goal → GoalPlanner (back-chaining) → GoalExecutor (FSM). See [[Goal Engine
Tasks	task	44 self-contained state machines with their own watchdogs. See [[Task System
Action / Pathfinding	action · pathfinding	BlockMiner, DigNav, ActionPack; A* with stand-ability checks
Knowledge	craft · mining	recipes, mining/smelt chains, tool tiers, ore & tree prospector
Safety net	task · coordination	BotTickCoordinator per-tick pipeline. See [[Safety Net
Entity	entity	AIPlayerEntity — a real server-side fake player
Infra	network · persist · memory · mixin · command · log	sync · save · memory · injection · commands · logging

Data flow of one request

1. Player sends a command / natural language, or IdleCoordinator triggers autonomous decision.
2. Perception builds a world snapshot (position, inventory, health, nearby blocks / entities).
3. Brain queries DeepSeek with the snapshot; the model returns tool calls.
4. A tool resolves into a Goal or directly a Task.
5. GoalPlanner back-chains the goal into a dependency-correct step sequence.
6. GoalExecutor dispatches steps one by one as Tasks.
7. Task drives Action primitives + pathfinding on the world.
8. Every tick, the safety net runs first and takes over when needed (survival first).
9. Results flow back into perception for the next round.

Design principles

• Determinism first — anything that can be done deterministically is never delegated to the LLM. The model decides what, not how.
• Rule G1 — self-contained tasks: a task never assigns sub-tasks; it calls shared primitives (BlockMiner / DigNav / ActionPack). No state-machines-within-state-machines fighting each other.
• Rule G2 — main-thread execution: all bot logic runs on the server main thread for thread-safe world access.
• Failures are observable & re-plannable — each step can succeed / fail / abort; failures bubble up to GoalExecutor to re-plan instead of silently hanging.
• Safety net backstop — whatever the upper layers decide, the per-tick safety net keeps the bot from needlessly drowning / burning / being swarmed.

At a glance

_{151 classes · 23.4K LOC · 56 tools · 44 task FSMs · 5-layer safety net}