# AI Builder User Manual

> Version 1.6.0 | Minecraft 1.20.4 | Fabric Mod

## Installation

Requires Minecraft 1.20.4, Fabric Loader 0.15.0 or later, Java 17 or later, and Fabric API. Install those dependencies, place `ai-builder-1.6.0.jar` in `.minecraft/mods/`, then start the game and press `K`.

## Initial Setup

The first launch creates `ai-helper/config/ai-builder.properties`. Set your API key before using AI:

```text
/aiconfig api_base_url YOUR_API_URL
/aiconfig api_key YOUR_API_KEY
/aiconfig model YOUR_MODEL_NAME
```

You can also press `K` → **AI Chat Settings** → **AI API Settings**. OpenAI-compatible APIs and Anthropic Messages APIs are supported. `api_format=auto` selects a format from the endpoint; edit the config to explicitly use `openai` or `anthropic`, then run `/aiconfig reload` when necessary.

## Keybindings

| Key | Function |
|---|---|
| `K` (default, rebindable) | Open the AI Builder settings menu |
| `Enter` | Send a chat message; place a structure or enter a folder in the structure browser |
| `Escape` | Close the current mod screen |
| `Page Up` / `Page Down`, mouse wheel | Scroll chat or file lists |
| Up/Down, `Backspace`, `Delete` | Navigate, go up, or delete a selected file in the unified structure browser |

Rebind `K` in Options → Controls → Key Binds under **AI Builder**. Other keys are fixed screen controls.

## Commands

### AI and utility commands

| Command | Description |
|---|---|
| `/ai <message>` | Chat with AI; it can perform supported building actions |
| `/aiblueprints` | List loaded TXT blueprints |
| `/ainew` | Clear conversation history |
| `/aistop` | Cancel the active AI request |
| `/aireject` | Reject all pending AI action requests (no request ID needed; same as clicking [No]) |

### Configuration commands

| Command | Description |
|---|---|
| `/aiconfig show` | Show API, model, web-search, and Tavily settings |
| `/aiconfig api_base_url <value>` | Set the API endpoint |
| `/aiconfig api_key <value>` | Set the API key |
| `/aiconfig model <value>` | Set the model |
| `/aiconfig tavily_api_key <value>` | Set the Tavily API key |
| `/aiconfig reload` | Reload a manually edited configuration file |

`/aiconfig` is not a generic key/value command. Change screenshot, context, and streaming in the settings screens; edit `api_format` and `rag_*` options directly in the configuration file and reload it. The UI display language is not configurable; it automatically follows the current Minecraft game language.

### Structures

Browse and place NBT / Litematica structures through the graphical browser: `K` → **Load Structures**.

> Chat-log forwarding and “Generate Test Logs” are supplied by the optional debug-menu mod, not by AI Builder commands.

> Developer note: the [Yes]/[No] chat buttons run commands via ClickEvent — `[Yes]` → `/aiconfirm <requestId>`, `[No]` → `/aireject <requestId>`. Running `/aireject` with no argument rejects all pending requests at once.

## Features

### AI Chat and Building

Open **AI Chat** with `K`, or use `/ai <message>`. The chat UI supports up to 20 messages (10 turns) of history, 1024-character input, TXT blueprint references, request cancellation, and incremental streaming output. Screenshot capture is disabled by default.

AI can place, fill, or clear blocks; give items; summon entities; set time/weather; create/place blueprints; and proactively query the terrain of a region (`[QUERY_REGION]`). A fill or clear operation is recommended to stay under about 10,000 blocks (not hard-enforced; going far beyond this may affect server performance), `give` is limited to 64 items, entity spawning to 20 entities, and a single terrain query to about 30,000 blocks in volume. `execute_command` never executes anything automatically — the AI can only pre-fill a suggested command into your chat input box; you must review it and press Enter yourself, and whatever permission you already have in-game is what applies.

V1/V2 blueprint coordinates are relative: X east, Y up, Z south, with the origin at player feet. V1 and MCBLUEPRINT v2 TXT blueprints are supported, and blueprints support a custom placement origin (relative to facing direction, or absolute); a confirmation screen lets you edit the origin before placement.

### RAG Knowledge Base

The knowledge base at `ai-helper/knowledge/` contains `info/` (reference documents), `structure/` (structure references), and `workflow.txt` (AI workflow, initially empty for user customization). Basic knowledge usage guidelines are built into the system prompt. Every AI request reloads the complete workflow and folder/file tree into the system prompt; edits take effect without restarting. Read reference contents on demand with `[KNOWLEDGE_FILE]relative/path[/KNOWLEDGE_FILE]`; Markdown documents in `info/` also support `[KNOWLEDGE]doc name[/KNOWLEDGE]`. Workflow and tree injection apply regardless of `rag_enabled`; retrieval tools still follow that setting. No encyclopedia documents are bundled. An existing `basic_info_en/` directory is migrated to `info/` when `info/` does not yet exist, preserving its files.

### AI Permission Settings

Press `K` → **AI Chat Settings** → **AI Permission Settings** (split out from AI Chat Settings) to control:

- **Allow AI to Use Vanilla Commands** (`vanilla_commands_enabled`, on by default): when off, the AI can only use the mod's built-in features and will not suggest any vanilla commands.
- **Tool Approval** (`tool_approval_mode`, defaults to `as_needed` for new installations): cycles through No Approval / As Needed / Always. As Needed approves changes, blueprints and camera shots; read-only tools run directly. Always also approves read-only tools. Vanilla command suggestions always remain pre-filled in chat for manual execution. Requests expire after 60 seconds. Legacy confirmation off maps to No Approval; on maps to Always.
- **Max tool-call rounds** (the `max_tool_rounds` setting, moved here from chat settings): caps the multi-round agentic tool-call loop.

Camera shots (`camera_shot_enabled`, on by default) have an independent toggle in AI Permission Settings. The AI uses `[CAMERA_SHOT]x,y,z,yaw,pitch[/CAMERA_SHOT]` to capture a view from specified world coordinates and angles for visual inspection; this is separate from `screenshot_enabled` for message screenshots. **Open Knowledge Folder** on the same screen opens this game instance’s `ai-helper/knowledge/` (`run/ai-helper/knowledge/` for the development client).

### Unified Structure Browser

Open **Load Structures** from the `K` menu to browse, search, delete, and place files in subfolders of:

- `ai-helper/structures/nbts/` for `.nbt` files;
- `ai-helper/structures/litematic/` for `.litematic` files;
- `ai-helper/structures/txts/` for V1/V2/V3 `.txt` blueprints.

NBT/Litematica placement skips `air` and `structure_void` and preserves block states, block-entity data, and structure entities. Legacy sign data is converted to the 1.20+ format. AI-generated TXT blueprints are saved in `ai-helper/structures/txts/ai-generated/`.

Click **Convert** at the top of the structure browser to batch-convert `.nbt`, `.litematic`, and `.txt` files into any target format. Pick source files, a target format, and a target folder; the conversion fully preserves block states, container items, and sign front/back text (including the legacy pre-1.20 `Text1`~`Text4` format).

### Selection Tool

Open **Selection Tool** from the `K` menu. Set two corner coordinates (or use the current position), confirm to render a highlight, then analyze/export the selection. Draft coordinates persist when the screen closes.

- **TXT / MCBLUEPRINT v2:** always exports container inventories and non-empty front/back sign text.
- **NBT:** preserves block-entity data.
- **Litematica:** preserves block-entity data and can include entities.

### Web Search, Fetch, and Screenshots

Web search requires `web_search_enabled=true` and a `tavily_api_key`. When AI requests a search, the mod asks Tavily for up to five results with a 120-second timeout. AI may also request a webpage fetch; it has a 30-second timeout and the resulting plain text is limited to 8,000 characters.

When `screenshot_enabled` is enabled, the chat UI closes for two ticks before capturing a screen image up to 512 px wide. It is saved temporarily as `ai-helper/screenshots/ai_chat_temp.png`; the `/ai` screenshot path is `ai_temp.png`.

## Configuration

Configuration file: `ai-helper/config/ai-builder.properties`

| Key | Default | Description |
|---|---|---|
| `api_base_url` | `https://api.kimi.com/coding/v1/messages` | API endpoint |
| `api_key` | `your-api-key-here` | API key; must be configured |
| `model` | `kimi-for-coding` | Model name |
| `screenshot_enabled` | `false` | Send a game screenshot from AI Chat |
| `context_enabled` | `true` | Enable multi-turn context |
| `web_search_enabled` | `true` | Allow Tavily web search |
| `tavily_api_key` | empty | Tavily API key |
| `stream_output_enabled` | `true` | Incrementally show AI responses |
| `max_tool_rounds` | `3` | Max rounds for the multi-round tool-call loop; 0 disables multi-round tool calls |
| `vanilla_commands_enabled` | `true` | Whether the AI is allowed to use vanilla commands (`execute_command`) |
| `tool_approval_mode` | `as_needed` | `never`, `as_needed`, or `always`; vanilla commands remain manually executed |
| `camera_shot_enabled` | `true` | Allow AI camera shots, independently of message screenshots |
| `api_format` | `auto` | `auto`, `openai`, or `anthropic` |
| `rag_enabled` | `true` | Whether knowledge retrieval tools (`[KNOWLEDGE]`, `[KNOWLEDGE_TREE]`, `[KNOWLEDGE_FILE]`) is enabled |
| `rag_max_docs` | `8` | Max documents nameable in a single `[KNOWLEDGE]` request |
| `rag_max_chars` | `20000` | Total character limit for knowledge base content returned to the AI |

**AI Chat Settings** controls the screenshot, context, web-search, and streaming toggles. **AI Permission Settings** controls the vanilla-commands toggle, tool approval mode, and max tool-call rounds. The API settings screen edits the endpoint, key, model, and Tavily key. Run `/aiconfig reload` after manual edits. The UI display language has no config option; it automatically follows the current Minecraft game language.

## Blueprint Format

```text
# MCBLUEPRINT v2
# name: example
# size: 5x6x5
# origin: 0,0,0
# Origin: structure northwest corner on the lowest layer; x=east, y=up, z=south
# Format: x,y,z  block_id  [key=value ...]

## BLOCKS

# --- Layer 1 (y=0) ---
2,0,2   oak_log   axis=y
3,0,2   short_grass
0,0,3   short_grass
2,0,4   short_grass
4,0,4   short_grass

# --- Layer 2 (y=1) ---
2,1,2   oak_log   axis=y

# --- Layer 3 (y=2) ---
0,2,0   oak_leaves   distance=4   persistent=false   waterlogged=false
1,2,0   oak_leaves   distance=3   persistent=false   waterlogged=false
2,2,0   oak_leaves   distance=2   persistent=false   waterlogged=false
3,2,0   oak_leaves   distance=3   persistent=false   waterlogged=false
0,2,1   oak_leaves   distance=3   persistent=false   waterlogged=false
1,2,1   oak_leaves   distance=2   persistent=false   waterlogged=false
2,2,1   oak_leaves   distance=1   persistent=false   waterlogged=false
3,2,1   oak_leaves   distance=2   persistent=false   waterlogged=false
4,2,1   oak_leaves   distance=3   persistent=false   waterlogged=false
0,2,2   oak_leaves   distance=2   persistent=false   waterlogged=false
1,2,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,2,2   oak_log   axis=y
3,2,2   oak_leaves   distance=1   persistent=false   waterlogged=false
4,2,2   oak_leaves   distance=2   persistent=false   waterlogged=false
0,2,3   oak_leaves   distance=3   persistent=false   waterlogged=false
1,2,3   oak_leaves   distance=2   persistent=false   waterlogged=false
2,2,3   oak_leaves   distance=1   persistent=false   waterlogged=false
3,2,3   oak_leaves   distance=2   persistent=false   waterlogged=false
4,2,3   oak_leaves   distance=3   persistent=false   waterlogged=false
1,2,4   oak_leaves   distance=3   persistent=false   waterlogged=false
2,2,4   oak_leaves   distance=2   persistent=false   waterlogged=false
3,2,4   oak_leaves   distance=3   persistent=false   waterlogged=false
4,2,4   oak_leaves   distance=4   persistent=false   waterlogged=false

# --- Layer 4 (y=3) ---
1,3,0   oak_leaves   distance=3   persistent=false   waterlogged=false
2,3,0   oak_leaves   distance=2   persistent=false   waterlogged=false
3,3,0   oak_leaves   distance=3   persistent=false   waterlogged=false
0,3,1   oak_leaves   distance=3   persistent=false   waterlogged=false
1,3,1   oak_leaves   distance=2   persistent=false   waterlogged=false
2,3,1   oak_leaves   distance=1   persistent=false   waterlogged=false
3,3,1   oak_leaves   distance=2   persistent=false   waterlogged=false
4,3,1   oak_leaves   distance=3   persistent=false   waterlogged=false
0,3,2   oak_leaves   distance=2   persistent=false   waterlogged=false
1,3,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,3,2   oak_log   axis=y
3,3,2   oak_leaves   distance=1   persistent=false   waterlogged=false
4,3,2   oak_leaves   distance=2   persistent=false   waterlogged=false
0,3,3   oak_leaves   distance=3   persistent=false   waterlogged=false
1,3,3   oak_leaves   distance=2   persistent=false   waterlogged=false
2,3,3   oak_leaves   distance=1   persistent=false   waterlogged=false
3,3,3   oak_leaves   distance=2   persistent=false   waterlogged=false
4,3,3   oak_leaves   distance=3   persistent=false   waterlogged=false
0,3,4   oak_leaves   distance=4   persistent=false   waterlogged=false
1,3,4   oak_leaves   distance=3   persistent=false   waterlogged=false
2,3,4   oak_leaves   distance=2   persistent=false   waterlogged=false
3,3,4   oak_leaves   distance=3   persistent=false   waterlogged=false

# --- Layer 5 (y=4) ---
2,4,1   oak_leaves   distance=1   persistent=false   waterlogged=false
1,4,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,4,2   oak_log   axis=y
3,4,2   oak_leaves   distance=1   persistent=false   waterlogged=false
2,4,3   oak_leaves   distance=1   persistent=false   waterlogged=false

# --- Layer 6 (y=5) ---
2,5,1   oak_leaves   distance=2   persistent=false   waterlogged=false
1,5,2   oak_leaves   distance=2   persistent=false   waterlogged=false
2,5,2   oak_leaves   distance=1   persistent=false   waterlogged=false
3,5,2   oak_leaves   distance=2   persistent=false   waterlogged=false
2,5,3   oak_leaves   distance=2   persistent=false   waterlogged=false
```

A V2 block line is `x,y,z   block_id   [key=value ...]`. `# name:`, `# size:`, and `# origin:` are optional metadata; lines beginning with `#` are comments. Legacy V1 character-grid blueprints remain compatible: rows go south, columns go east, and spaces mean air.

V3 uses a `# MCBLUEPRINT v3` header and the same block-line syntax as V2, but coordinates are absolute world coordinates. Origin translation is unsupported and `# origin:` is ignored. V1/V2 retain relative coordinates. Manual V3 placement locks the origin to `0,0,0`, disables coordinate editing and hides the Reset to Player button. Blocks always use the absolute world coordinates in the file.


## File Structure

```text
.minecraft/
├── ai-helper/
│   ├── config/ai-builder.properties
│   ├── structures/
│   │   ├── nbts/
│   │   ├── litematic/
│   │   └── txts/
│   │       └── ai-generated/
│   ├── knowledge/
│   │   ├── info/
│   │   ├── structure/
│   │   └── workflow.txt
│   └── screenshots/
│       ├── ai_temp.png
│       └── ai_chat_temp.png
└── mods/ai-builder-1.6.0.jar
```

All structure directories support arbitrarily nested folders.

## FAQ and Notes

**AI does not respond:** Run `/aiconfig show` to check the key and endpoint, then verify network access. The optional debug-menu can provide chat logs for diagnosis.

**Changing streaming output:** Use `K` → **AI Chat Settings**. There is no `/aiconfig stream_output_enabled` command. The UI display language cannot be switched manually; it follows the current Minecraft game language.

**Manual configuration changes:** Run `/aiconfig reload`; a restart is unnecessary.

**Safety and performance:** API keys are stored locally. AI operations are irreversible, so back up important worlds. Search and fetching send requests to external services. Large structure placement can cause brief lag.

## License

MIT License

Author: liuzeen1234
Source: https://github.com/liuzeen1234/minecraft-AI-helper
