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:

/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

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

Commands

AI and utility commands

Configuration commands

/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

/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

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

# 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

.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