This guide walks you through installing Foundry and building your first Minecraft mod from scratch. No Java experience required.
By the end, you'll have a working mod running in Minecraft - built with AI, with a complete understanding of every step along the way.
What You'll Need
- A Windows PC (macOS and Linux support coming soon)
- 8GB RAM minimum (16GB recommended)
- 2GB free disk space (5GB+ recommended for project storage space)
- A stable internet connection (needed for AI features)
- A Microsoft account - the same one you use for Minecraft
That's it. You don't need to install Java, Gradle, or any Minecraft-specific tools. Foundry handles all of that automatically.
Step 1: Download and Install Foundry
Head to the download page and download Foundry.
Run the installer and follow the setup wizard. Foundry installs like any other desktop application - it takes 2-3 minutes.
When you first launch Foundry, you'll be prompted to sign in with your Microsoft account. No separate account creation is needed.
Step 2: Create Your First Project
Click New Project in the Foundry home screen.
You'll see a project creation dialog with two choices:
Mod Loader: Choose Fabric or NeoForge. If you're not sure which to pick, check out our Fabric vs NeoForge guide. For this tutorial, either works.
Minecraft Version: Choose the latest available version.
Project Name: Give your mod a name. Something simple like "my-first-mod" works.
Click Create. Foundry will:
- Configure a JDK automatically
- Set up Gradle with the correct build script
- Scaffold a new Fabric or NeoForge mod project
- Download decompiled Minecraft source code for the AI to reference
This takes 30-60 seconds. When it's done, you'll see your project open in the Foundry IDE.
Step 3: Understand What You're Looking At
Foundry has two modes, switched using the Builder and Developer tabs at the top center of the window. You start in Builder mode by default.
Builder mode is chat-first. The left side is the AI chat panel - describe what you want to build here. The right side shows build output and logs. There's no file tree in this view; the focus is the conversation with the AI.
Developer mode gives you the full IDE layout:
- Sidebar (left): Your project's files, plus Minecraft's decompiled source code and the Fabric or NeoForge API sources. The Minecraft and API sources are read-only references the AI uses.
- Editor (center): A full Monaco-based code editor. Click any file in the sidebar to open it.
- Chat panel (right): The same AI chat, now alongside the code.
- Output panel (bottom): Build output, logs, and errors.
Project controls sit just below the title bar in both modes: your project name on the left, and four buttons on the right - Port, Reveal Jar, Build, and Run.
For this guide, we'll work in Builder mode. Switch to Developer mode any time you want to see or edit the code the AI writes.
Step 4: Build Something
Let's create a custom item - a simple "Lucky Coin" that gives the player a random positive effect when used.
Open the AI panel and type:
"Add a new item called Lucky Coin. When the player right-clicks while holding it, they get one of the following effects chosen at random: Speed II for 30 seconds, Regeneration II for 15 seconds, or Strength I for 60 seconds. The item has 10 uses."
Press Enter and watch the AI work.
You'll see it:
- Search through Minecraft source code for the right APIs
- Create a Java class for your item
- Register the item in your mod's initialization code
- Add a placeholder texture
- Attempt a build
If the build succeeds, you'll see a green status. If there's an error, the AI reads it and fixes it automatically - usually within one or two attempts.
Step 5: Test Your Mod
Click the Run button (or ask Ember to run the mod). Foundry launches Minecraft with your mod loaded.
In game:
- Open a creative inventory
- Search for "Lucky Coin" - it should appear
- Hold it and right-click
You should see a random effect apply. If something doesn't work as expected, go back to the AI panel and describe what's wrong:
"The Lucky Coin isn't giving effects - nothing happens when I right-click. Fix it."
The AI will diagnose and fix the issue.
Step 6: Explore the Code
This is optional, but worthwhile. Switch to Developer mode using the tab at the top, then open the file the AI created for your item in the sidebar. For Fabric, it'll be something like src/main/java/com/yourname/yourmod/item/LuckyCoinItem.java.
Even if you don't know Java, you'll recognize the structure: a class that extends Minecraft's item class, with a method that runs when the item is used, calling effect-related methods with the random logic you described.
This is real, production-quality Java. You can modify any value directly - change the effect durations, add or remove effects, adjust use count - and then rebuild.
What's Next
Now that you have a working project, here are some things to try:
- Add more items: Ask the AI to add a sword, a food item, or a tool with custom behavior
- Add a block: "Create a block called Ember Ore that generates underground and drops 2-4 Ember Fragments"
- Add world generation: Ask the AI to add your block to world generation
- Learn from the code: Browse the files the AI created - it's one of the best ways to learn Java in context
For a deeper dive into what Foundry's AI can do, read the complete AI Minecraft modding guide.
Download Foundry and build your first mod today.