AI Villagers [Gemini]

# 🧠 AI Villagers

### Give Minecraft villagers a mind of their own.

AI Villagers transforms ordinary Minecraft villagers into intelligent characters with **AI-powered conversations, personalities, persistent memories, and autonomous decision-making**.

Instead of villagers simply standing around waiting for trades, they can communicate, remember what you tell them, evaluate their surroundings, pursue goals, react to danger, and make their own decisions.

---

## ✨ Features

### 💬 AI Conversations

Talk directly with villagers using Minecraft chat.

Shift + Right Click an enabled villager to begin a conversation, then type normally in chat.

Villagers can:

- Respond naturally to your messages
- Discuss their surroundings
- Remember information from conversations
- Develop familiarity with players
- Use their individual personality when responding

Normal Minecraft trading still works when you interact with a villager normally.

---

### 🧠 Persistent Memory

Villagers aren't completely forgetful.

Each AI villager has its own memory and can remember information from previous conversations.

You can even teach them facts directly.

For example:

`/aivillagers remember Naman owns the large wheat farm`

This information becomes part of that villager's memory.

---

### 🎭 Personalities

Not every villager thinks the same way.

AI Villagers gives villagers individual personality traits that influence how they behave and respond.

Some villagers may be more:

- Brave
- Social
- Introverted
- Helpful
- Cautious

Their personality can affect their conversations and autonomous decisions.

---

# 🤖 Autonomous Villagers

This is where AI Villagers becomes more than a conversation mod.

When autonomous behavior is enabled, villagers can observe their surroundings and decide what they should do next.

They can pursue goals such as:

- 🌾 Gathering resources
- 🍞 Finding food
- 🏠 Returning home
- 😴 Sleeping
- 🧑‍🤝‍🧑 Socializing
- 🚶 Following other villagers
- 🏃 Fleeing from danger
- ⚔️ Fighting hostile mobs
- 📍 Moving toward useful locations

Villagers continuously evaluate their situation and choose from a controlled set of actions.

The AI **cannot execute arbitrary Minecraft commands or unrestricted actions**. Decisions are validated and passed through the mod's action system before being executed.

---

# 🧠 How the AI Works

AI Villagers uses **Google Gemini** as its AI brain.

The mod collects a compact view of the villager's situation, including relevant world information and needs, and asks Gemini to make a decision or generate a conversational response.

The result is then validated before the villager performs an action.

```text
Minecraft World
      ↓
Villager Perception
      ↓
Needs & Situation
      ↓
🧠 Gemini
      ↓
Validated Decision
      ↓
Villager Action

🔑 Setting Up Gemini

AI Villagers uses a Bring Your Own API Key system.

You need your own Google Gemini API key.

1. Get a Gemini API key

Create a key through Google AI Studio.

2. Launch Minecraft once

The mod will create its configuration file.

3. Open

.minecraft/config/ai-villagers.json

4. Add your API key
"apiKey": "YOUR_GEMINI_API_KEY"
5. Restart Minecraft

Or use:

/aivillagers reload

⚠️ Never share your Gemini API key with anyone.

Do not post your key in Discord, screenshots, GitHub, Modrinth comments, or bug reports.

If you accidentally expose your key, revoke it through Google and create a new one.

⚙️ Configuration

AI Villagers provides configuration options for controlling autonomous behavior.

Important options include:

Option    Description
autonomousVillagers    Enables or disables autonomous villager behavior
autonomousCombat    Allows autonomous villagers to react to hostile mobs
maxConcurrentDecisions    Limits how many AI decisions can happen simultaneously
maxActionsPerDecision    Limits actions produced by a single decision

If you're running a large village, lowering the concurrency settings can help reduce AI/API activity.

🛠️ Commands

Use:

/aivillagers enable

Enable AI behavior for the villager you're looking at.

/aivillagers disable

Disable AI behavior for the targeted villager.

/aivillagers status

View information about the targeted AI villager.

/aivillagers remember <fact>

Teach the villager a fact.

Example:

/aivillagers remember Naman owns the large wheat farm
/aivillagers forget

Clear the targeted villager's stored memory.

/aivillagers reload

Reload the AI Villagers configuration.

Commands that target a villager require you to be looking at a villager within the required range.

💬 Talking With a Villager
Start
Look at an AI-enabled villager.
Sneak + Right Click the villager.
You should see:

AI Villagers: Now talking with Villager...

Type your message normally in Minecraft chat.
Stop

You can end the conversation by:

Sneak + Right Click the same villager again
Using /aivillagers stop
Moving away far enough for the existing conversation distance rule to trigger
⚠️ Important Things To Know
🌐 Internet connection

AI responses require communication with the Gemini API.

If your internet connection is slow or unavailable, responses may take longer or fail.

🔑 API limits

Gemini API usage is subject to Google's own quotas, limits, and policies.

AI Villagers cannot control those limits.

🐌 AI responses may take time

AI responses are not instant.

Depending on your connection, API availability, model processing, and server performance, a response can take several seconds.

Do not spam messages while a villager is already answering.

🧠 AI isn't perfect

Villagers may occasionally make strange, incorrect, funny, or unexpected decisions.

That's part of the experiment.

The mod validates AI decisions, but it does not guarantee that every AI-generated response or decision will be sensible.

⚔️ Autonomous combat

Autonomous combat is still an evolving feature.

Villagers may sometimes make unexpected tactical decisions, especially in unusual terrain or dangerous situations.

🚫 What NOT To Do

Please do not:

Share your Gemini API key.
Upload your ai-villagers.json containing your API key.
Spam villagers with hundreds of messages.
Run extremely large numbers of autonomous villagers without testing server performance.
Report an API quota error as a Minecraft/mod bug without checking your Gemini API status first.
Assume an AI response represents an intentional fixed behavior of the mod.
🐛 Found a Bug?

Found something broken?

Please report it!

Before reporting:

Reproduce the issue if possible.
Check your Minecraft log for [AI Villagers] messages.
Note what you were doing when the issue happened.
Include your Minecraft version, Fabric version, AI Villagers version, and relevant mods.
💬 Need help?

Join the AI Villagers Discord and ping @RealNamanYT when you need help or want to report an issue.

When reporting a bug, please include:

Minecraft version:
Fabric Loader version:
AI Villagers version:
Other relevant mods:

What happened:
What did you expect to happen:

Relevant log:

Never include your Gemini API key in a bug report.

❤️ Feedback

AI Villagers is an evolving project.

If you enjoy the mod, find something funny, discover an unexpected villager behavior, or have an idea for a new feature, we'd love to hear about it.

Your feedback helps make the villagers smarter.

📜 License

AI Villagers is released under the license specified on this Modrinth project.

See the repository/project files for the complete license text.