Smart Villagers AI transforms ordinary villagers into intelligent NPCs powered by the DeepSeek API. Instead of acting as simple trading stations, villagers can hold natural conversations, remember previous interactions, react to their profession, build relationships with players, offer survival advice, and respond to the world around them.

Features

Feature	Description
AI-Powered Conversations	Dynamic conversations with villagers powered by DeepSeek AI
Profession Personalities	Villagers respond based on their profession and knowledge
Villager Memory	Remember conversations, trades, reputation changes, interactions, and recent events
Relationships	Villagers react differently depending on how players treat them
Context Awareness	Responses can consider biome, weather, time, danger, equipment, player status, and village conditions
Smart Hints	Receive exploration, farming, trading, combat, resource, and progression advice
Async Processing	AI requests run asynchronously to minimize game-thread impact
Fully Configurable	Control AI model, tokens, temperature, memory, cooldowns, rate limits, timeouts, and features
Fallback Dialogue	Villagers remain usable without a configured or available live AI API
Server Friendly	Cooldowns, rate limits, spam protection, cost controls, and server-side API security

AI-Powered Conversations

Engage in dynamic conversations with villagers powered by DeepSeek AI.

Villagers can:

• Answer questions
• Discuss Minecraft topics
• React to player actions
• Participate in roleplay scenarios
• Provide useful gameplay information

Profession-Based Personalities

Each villager profession has its own personality and knowledge.

Examples include:

• Farmers discussing crops and food
• Librarians sharing knowledge
• Clerics discussing mysteries
• Armorers talking about gear
• Fishermen sharing fishing tips
• Nitwits providing questionable wisdom

Villager Memory

Villagers can remember:

• Previous conversations
• Trades
• Reputation changes
• Player interactions
• Recent events

This allows conversations to feel more natural and persistent.

Relationship & Reputation System

Villagers react differently based on how players treat them.

Influence reputation through:

• Trading
• Helping villagers
• Defending villages
• Attacking villagers
• Stealing resources
• Causing trouble

Build trust—or become infamous.

Context-Aware Responses

Villagers can consider:

• Biome
• Weather
• Time of day
• Nearby dangers
• Equipment
• Player status
• Village conditions

This makes conversations feel connected to the actual world.

Smart Hints & Survival Advice

Villagers can provide:

• Exploration tips
• Farming advice
• Trading suggestions
• Combat warnings
• Resource recommendations
• Progression guidance

Async API Processing

All AI requests are processed asynchronously to minimize performance impact and avoid blocking the game thread.

Configuration

Smart Villagers AI creates gameplay settings on first launch:

config/smartvillagers/config.toml

That path is under your Minecraft instance or dedicated server root (the same config folder other mods use). The file is written only if it does not already exist.

The generated file does not include an API key. Do not look for [smartvillagers.api] or apiKey there.

Live AI replies need a DeepSeek API key (not a downloadable file):

1. Create a key at https://platform.deepseek.com/api_keys — official page linked from DeepSeek API Docs.
2. Set DEEPSEEK_API_KEY on the game/server process, or create config/smartvillagers/secrets.toml yourself:

apiKey = "YOUR_DEEPSEEK_API_KEY"

secrets.toml is never generated automatically. Prefer the environment variable on servers. Never share your key.

Without a key, villagers still use local fallback dialogue.

Fallback Dialogue

If the API is disabled, unavailable, or not configured, villagers can still use fallback dialogue so the mod remains usable without live AI access.

Server-Friendly Design

Smart Villagers AI includes:

• Cooldowns
• Rate limits
• Spam protection
• Cost controls
• Server-side API security

Commands

/villagerai reload
/villagerai info
/villagerai toggle
/villagerai memory clear
/villagerai debug

Commands may vary between releases.

Installation

1. Install Fabric, Forge, or NeoForge for the file you downloaded.
2. Fabric only: also install Fabric API into mods/.
3. Place Smart Villagers AI in mods/.
4. Launch the game or server once. Confirm config/smartvillagers/config.toml appeared.
5. Optionally add a DeepSeek key (DEEPSEEK_API_KEY or config/smartvillagers/secrets.toml).
6. Restart or run /villagerai reload.
7. Stand near a villager and chat normally (not right-click).

Privacy & AI Notice

When AI conversations are enabled:

• Player messages may be sent to the configured DeepSeek API.
• API keys should remain private.
• Sensitive information should never be shared through villager conversations.
• Server owners should inform players when AI chat is enabled.

Compatibility

Supported:

• Vanilla Villagers
• Singleplayer
• Dedicated Servers

Planned or release-dependent support:

• Minecraft 1.20.1+
• Minecraft 1.21+
• Forge
• NeoForge
• Fabric

Always verify compatibility with the specific release before installing.

Frequently Asked Questions

Do I need to download the DeepSeek API?

No. Create a key at platform.deepseek.com/api_keys and add it as described above. There is no DeepSeek API jar.

Where is the config file?

<instance or server>/config/smartvillagers/config.toml, created on first launch if missing. Gameplay settings live there. The API key goes in the DEEPSEEK_API_KEY environment variable or config/smartvillagers/secrets.toml (never auto-generated).

Do I need a DeepSeek API key?

Only for live AI. Fallback dialogue works without one.

Does the mod work offline?

Partially. Fallback dialogue works offline, but AI conversations require internet access.

Will it lag my server?

The mod uses asynchronous processing and includes cooldowns to reduce performance impact.

Can villagers remember players?

Yes. When memory is enabled, villagers can remember conversations, trades, and reputation-related events.

Can I disable memory?

Yes. Memory can be disabled in the config.

Can I limit API usage?

Yes. Cooldowns, token limits, message limits, and global rate limits can be used to control usage and costs.

Is it compatible with modpacks?

Yes. Smart Villagers AI is designed for RPG, survival, adventure, and roleplay modpacks.

Always test compatibility with your specific setup.

Roadmap

Planned features:

• Dynamic Villager Quests
• AI-Generated Lore Books
• Village Gossip Networks
• Raid Panic Dialogue
• Wandering Trader Stories
• Voice Support
• Local AI Models
• Offline AI Support
• Advanced Roleplay Features

Community & Support

• Discord: https://discord.gg/TJc3CxR4jK
• GitHub: https://github.com/MeherBenSalem
• Website: https://nightbeam.dev
• Store: https://nightbeam.dev/store
• CurseForge: https://www.curseforge.com/members/nightbeamstudio/projects
• Modrinth: https://modrinth.com/organization/nightbeam