Developer Guide en

Developer Guide

For developers who want to read, modify, or extend AIBot. Start with Architecture for the big picture.

Build & run

./gradlew clean build   # full build (make sure it passes before a PR)
./gradlew runServer     # dev server
./gradlew runClient     # dev client

Version compatibility (important)

This project pins Yarn 1.21.3+build.2. Minecraft / Fabric API signatures change across versions — verify the current signature before touching:

• item components
• eating / food properties
• fuel registration
• mining speed
• furnace inventory
• client networking

Built-in verification tools

AIBot ships two diagnostic commands supporting "change → verify → regression":

Command	Purpose
/aibot verify <bot> <feature>	Run built-in scenarios (nav around obstacles / gaps / descent / mining / combat) and observe real behavior
/aibot deplint <bot> <spec>	Offline-audit a goal's plan chain (just the GoalPlanner output, no execution)

Plus structured logs / replay / profile:

/aibot observe tps
/aibot observe profile <bot>
/aibot observe replay …

Extend: add a new task

1. Extend AbstractTask, implement onStart / onTick / onAbort.
2. Follow the Task System: G1 no sub-task assignment inside (call shared primitives BlockMiner / DigNav / ActionPack); G2 touch the world only on the main thread.
3. For stationary tasks, override isWaiting() to true and bring your own NO_PROGRESS / timeout watchdog.
4. Finish with complete() / fail(reason); make the failure reason clear (for re-planning and log diagnosis).

Extend: add a new tool

1. Register via register("tool_name", description, schema, [Group], handler) in ToolRegistry.
2. Pick the right Group (low-level / memory / coordination, or default high-level) — affected by the brain config toggles (see Configuration).
3. In the handler, resolve params into a Task System or Goal Engine rather than touching the world directly — keep LLM plans, Tasks execute.

Extend: add a new goal

1. Add a variant to the sealed Goal type.
2. Add the "how to acquire" logic in GoalPlanner's ensureItem / planning branches.
3. Validate the back-chain with /aibot deplint before live-testing.

Code map

brain/        Brain: LLM requests, ToolRegistry, ActionDispatcher
goal/         Goals: Goal, GoalPlanner, GoalExecutor
task/         Task state machines + coordinators + watchdogs
action/       low-level action primitives
pathfinding/  A* pathfinding & stand-ability
craft/ mining/ recipes & ore knowledge
entity/       AIPlayerEntity
command/      /aibot commands
network/ persist/ memory/ observe/ log/ mixin/   infrastructure

See Architecture. Issues & PRs welcome 🙌