# AI Builder User Manual

> Version 1.4.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.4.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**. 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 |
| `/ai blueprints` | List loaded TXT blueprints |
| `/ai reload_blueprints` | Reload TXT blueprints from disk |
| `/ai test_stairs` | Place a stair-orientation debug sample |
| `/ainew` | Clear conversation history |
| `/aistop` | Cancel the active AI request |
| `/aipos` | Show the current coordinates and dimension |

### 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 web_search <on/off>` | Enable or disable web search |
| `/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, streaming, and language in the settings screens; edit `api_format` directly in the configuration file and reload it.

### Structure commands

| Command | Description |
|---|---|
| `/ainbt list` | List NBT and Litematica structures |
| `/ainbt info <filename>` | Show NBT or Litematica structure details |
| `/ainbt all` | Show a summary of all structures |
| `/ainbt place <filename>` | Place an NBT or Litematica structure at player feet |

`/ainbt` has no no-argument GUI. Open the graphical browser through `K` → **Load Structures**.

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

## 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; teleport; and create/place blueprints. A fill or clear operation is limited to 10,000 blocks, `give` to 64 items, and entity spawning to 20 entities. `execute_command` runs with permission level 2, but unsafe server-administration, moderation, and stop/save root commands are rejected; AI cannot run arbitrary vanilla commands.

Blueprint coordinates are relative: X east, Y up, Z south, with the origin at player feet. V1 and MCBLUEPRINT v2 TXT blueprints are supported.

### 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 `.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/`.

### 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 |
| `language` | `en_us` | `zh_cn` or `en_us` |
| `api_format` | `auto` | `auto`, `openai`, or `anthropic` |

**AI Chat Settings** controls the four Boolean settings. The API settings screen edits the endpoint, key, model, and Tavily key. Run `/aiconfig reload` after manual edits. Change language through `K` → **Mod Language**; the next client startup resets it to the current Minecraft 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.

## File Structure

```text
.minecraft/
├── ai-helper/
│   ├── config/ai-builder.properties
│   ├── structures/
│   │   ├── nbts/
│   │   ├── litematic/
│   │   └── txts/
│   │       └── ai-generated/
│   └── screenshots/
│       ├── ai_temp.png
│       └── ai_chat_temp.png
└── mods/ai-builder-1.4.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 language or streaming:** Use `K` → **Mod Language** and `K` → **AI Chat Settings**, respectively. There are no `/aiconfig language` or `/aiconfig stream_output_enabled` commands.

**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
