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

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

# 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