🎨 falcraft - AI-Powered 3D Generation for Minecraft

A Fabric mod for Minecraft 1.21.1 that brings AI-powered 3D model generation directly into your game.

📺 Quick Demo

▶️ Watch on YouTube - See falcraft in action!

🚀 Quick Start

1. ⬇️ Download Falcraft
2. ⬇️ Download Fabric API
3. Drop both JARs in .minecraft/mods/
4. Run /fal setkey "YOUR_KEY" (get key here)

📖 Full installation guide | Requires Minecraft 1.21.1 + Fabric Loader

🎮 Commands

Generate 3D Structures

/fal generate <size> <prompt>

Examples:

/fal generate 48 medieval castle
/fal generate 64 spongebob squarepants
/fal generate 96 ancient temple

Controls in preview mode:

• Right-click - Place the structure
• G - Rotate 90°

Size guide: 16-32 (small), 48-64 (recommended), 96-128 (large/detailed)

Generation takes ~30 seconds using Z-Image + SAM-3D pipeline.

Legacy Mode (Meshy-6)

For UV-textured models (~7 minutes):

/fal generate legacy <size> <prompt>

Remix Block Textures (Coming soon)

AI-powered texture remixing with undo/reset functionality - stay tuned!

⚙️ Setup Details

1. Install Fabric Loader + Fabric API for MC 1.21.1

2. Drop the mod JAR in .minecraft/mods/

3. Launch Minecraft and run:

   /fal setkey "YOUR_API_KEY"
   

   Get your API key at fal.ai/dashboard/keys

   Note: Wrap your API key in quotes to handle the special characters.

That's it! Your key is saved to config/falcraft/api-key.txt.

Check Status

/fal status

Shows if your API key is configured.

💰 API Cost

This mod uses fal.ai's cloud APIs. You'll need to add credits to your account.

Cost Breakdown (Per Structure)

Step	Model	Cost
1. Text → Image	Z-Image Turbo	~$0.005-0.008
2. Image → 3D	SAM-3D Objects	$0.02 (flat)
3. Prompt fix*	OpenRouter Vision	~$0.001

Total: ~$0.025-0.03 per generation (regardless of Minecraft size)

*Only triggered when the 3D segmentation fails on complex/abstract prompts

🧠 How It Works

1. Z-Image Turbo generates a 2D image from your prompt
2. SAM-3D converts the image to a 3D GLB model with vertex colors
3. Voxelizer converts the mesh to Minecraft blocks using triangle-voxel intersection
4. Block Mapper matches colors using CIE-LAB perceptual color space (100+ block palette)
5. Ghost Preview shows the structure before placement
6. Animated Build places blocks layer-by-layer

🐛 Troubleshooting

• "API key not configured" - Run /fal setkey "YOUR_KEY" (with quotes) or check with /fal status
• 403 error - Your fal.ai account needs credits. Add billing here
• Structure not visible - Look where you want to place (up to 200 blocks away)
• Colors look off - The 100+ block palette maps colors as close as Minecraft allows

📜 License

CC0 1.0 - Public domain. Use freely!

Built with Fabric and fal.ai.