Overview

Speaking Villagers redefines Minecraft villagers, giving them AI-powered personalities, quests, and dynamic interactions. With persistent memory and customizable personalities, villagers respond contextually to your actions, equipment, and surroundings. Quest and interaction data are saved across sessions and accessible for editing outside the game.

Features

AI-Driven Villager Conversations
Villagers generate responses shaped by:

• Player Context: Reputation, inventory, and surroundings influence dialogue.

• Assigned Styles: Personalities like Friendly or Grumpy modify responses, saved persistently between sessions.

• Memory:

  • Recall past interactions within and between sessions.

  • Conversation logs are stored in .minecraft/speakingvillagersmod/conversations.

• Multilingual Support: Villagers support all Minecraft-compatible languages for immersive experiences.

Persistent Quests
Villagers assign gather-style quests:

• Profession-Specific Tasks:

  • Farmers: Request crops.

  • Librarians: Ask for books.

• Reward Tiers: Tiered rewards based on item rarity (e.g., Iron Ingots, Netherite Ingots).

• Expanded Variety: New quest types and better balance.

• Data Persistence: Stored in .minecraft/speakingvillagersmod/questdata/quest_data.dat.

Text-to-Speech (TTS)
Villagers vocalize responses using TTS:

• Persistent Voices: Based on age and gender, saved across sessions.

  • Distinct voices for male and female baby villagers.

• Enhanced Voice Quality: Install Natural Voice SAPI Adapter (Windows only).

Friendship System

• Befriend Villagers: Initiate friendships, make villagers follow you, and display heart effects.

• Unfriend Villagers: End friendships as needed.

• Data Persistence: Friendship data is saved in .minecraft/speakingvillagersmod/friendships.json.

• Dynamic Friendships: Triggered and ended based on player reputation.

Gift System
Villagers can pick up dropped items:

• Behavior: Treated as gifts and displayed in the villager’s hand.

• Customization: Disabled by default; toggle in mod configuration.

Commands

/speak <message>

• Function:
  Engage the nearest villager in conversation, generating context-aware responses.

• Syntax:
  /speak <message>

• Example:
  /speak How are you today?

• Requirement:
  Requires an OpenAI API key to generate responses.

/setvillagerstyle <villagerName> | <styleName>

• Function:
  Assigns a specific personality to a named villager, affecting dialogue.

• Syntax:
  /setvillagerstyle <villagerName> | <styleName>

  • <villagerName>: Name of the villager (case-insensitive).

  • <styleName>: Style to assign (e.g., Friendly, Grumpy, Philosopher, Funny).

• Example:
  /setvillagerstyle Farmer Joe | Friendly

/befriend

• Function:
  Manually initiate a friendship with the nearest villager.

• Syntax:
  /befriend

• Effect:
  The villager follows you and displays heart effects.

• Example:
  /befriend

/unfriend

• Function:
  End a friendship with the nearest villager.

• Syntax:
  /unfriend

• Effect:
  The villager stops following you, and heart effects cease.

• Example:
  /unfriend

Configuration

General Settings

• enableMod (Default: true):
  Enables or disables the mod.

• aiModel (Default: GPT-4):
  Choose AI models: GPT-3.5, GPT-4, or GPT-4 Omni.

• maxTokens (Default: 150):
  Adjust token limit for AI responses (range: 50–500).

• maxWords (Default: 80):
  Set maximum response length (range: 10–200).

Quest Settings

• questChancePercentage (Default: 10%):
  Chance of receiving a quest during interactions.

• Reward Balance:
  Configure tiered rewards based on difficulty and rarity.

Visual Effects

• disableVisualEffects (Default: false):
  Toggle all visual effects globally.

• enableAuraEffects (Default: true):
  Toggle glowing auras during interactions.

• enableHeartEffects (Default: true):
  Enable heart effects when befriending villagers.

• enableQuestEffects (Default: true):
  Show visual effects for active quests.

Audio Settings

• ttsVolume (Default: 80%):
  Set TTS volume level (range: 0–100%).

Persistence

All villager interactions and data are stored persistently and can be accessed outside the game:

1. Conversation Logs:
   Stored in .minecraft/speakingvillagersmod/conversations. Editable for custom dialogue.

2. Quest Data:
   Saved in .minecraft/speakingvillagersmod/questdata/quest_data.dat.

3. Friendships:
   Stored in .minecraft/speakingvillagersmod/friendships.json.

4. Villager Styles:
   Saved and customizable for personalized villager behavior.

FAQs

Q: Why does it cost to use this mod, and how much does it cost?

A: The /speak command uses OpenAI's API to generate responses. This API is a paid service, and costs depend on the chosen AI model and how often the command is used.

• Model Costs:

  • GPT-3.5-turbo: Approximately $0.002 per 1,000 tokens. This is the most budget-friendly option.

  • GPT-4: Costs around $0.03–$0.06 per 1,000 tokens, offering higher-quality responses.

• Monthly Estimate:

  • Casual Use: Typically under $5 per month.

  • Frequent Use: Costs may range from $10–$30 or more, depending on the number of requests and response lengths.

Important Information:

• Prepaid Only: OpenAI requires you to add credits or a payment method in advance. Without this, the mod won't generate responses, so there’s no risk of accidental charges.

• Responsible Use: Monitor your API usage and spending. OpenAI provides tools to track usage and set limits to avoid exceeding your budget.

Q: Why isn’t /speak generating responses?

• A: Ensure your OpenAI API key is set as an environment variable (OPENAI_API_KEY). Verify the key's validity and ensure you have sufficient API credits.

Q: Can you add a voice that sounds like normal Minecraft villagers?
A: Unfortunately, the mod relies on SAPI (Speech Application Programming Interface) voices, which are part of your system's Text-to-Speech (TTS) setup. These voices are not designed to mimic the sounds of Minecraft villagers but are instead optimized for natural speech.

However, there’s a silver lining:

• Multilingual Support: SAPI voices support multiple languages, letting villagers speak in any Minecraft-compatible language, adding a unique layer of immersion.

• High Quality: The voices are clear and customizable, with distinct tones for age and gender, making interactions feel more personal.

While a true villager-like voice isn't possible due to the technical constraints of using SAPI, the current system offers a robust, immersive roleplay experience that's both flexible and globally accessible!

Q: How do I assign a personality to a villager?

• A: Use the /setvillagerstyle <villagerName> | <styleName> command. Replace <villagerName> with the villager's name and <styleName> with a valid style like Friendly or Grumpy.

Q: Can I use this mod in multiplayer?

• A: Multiplayer compatibility is untested. Use cautiously on servers, as unexpected behavior may occur.

Q: How can I enable villagers to pick up items as gifts?

• A: Enable the enableGifts setting in the mod configuration using Mod Menu or by editing the speakingvillagers.json file. Dropped items within a 2-block radius will be treated as gifts.

Q: Is there a way to disable all visual effects?

• A: Yes, set disableVisualEffects to true in the mod configuration to disable all visual effects globally.

Q: Should I use the OpenAI API responsibly?

• A: Absolutely! Remember that API usage incurs real costs. Use the mod's features thoughtfully, especially when experimenting with longer or more frequent dialogues. If you’re sharing this mod on a server or with friends, ensure they understand the associated costs as well.

Known Issues and Limitations

1. API Dependency:
   Dialogue generation requires an OpenAI API key. Without it, villagers remain silent.

2. Singleplayer Only:
   Multiplayer compatibility is untested.

3. TTS Limitations:
   Optimized for Windows systems with Natural Voice SAPI Adapter.

Have fun!