animal-crossing-llm-mod

animal-crossing-llm-mod

AI-powered dialogue generation for Animal Crossing villagers using LLMs

Stars: 253

Visit
 screenshot

The Animal Crossing LLM Mod transforms the game into an AI-powered conversation experience by generating dynamic, contextual dialogue for villagers in real-time. It reads dialogue memory, generates AI responses, writes new dialogue back to the game, and creates natural and contextual conversations. The mod is experimental software with known bugs and is currently only tested on macOS. Users can interact with villagers in Animal Crossing using AI-generated responses, enhancing the gameplay experience.

README:

๐Ÿฌ Animal Crossing LLM Mod

Transform Animal Crossing into an AI-powered conversation experience! This mod uses Large Language Models to generate dynamic, contextual dialogue for villagers in real-time.

โš ๏ธ EXPERIMENTAL SOFTWARE: This mod has known bugs and is only tested on macOS. Use at your own risk! PRs welcome to help improve it.

๐ŸŽฅ What This Does

Ever wanted to have meaningful conversations with your Animal Crossing villagers? This mod:

  • Reads dialogue memory from Animal Crossing running in Dolphin emulator
  • Generates AI responses using Google Gemini or OpenAI models
  • Writes new dialogue back to the game in real-time
  • Creates dynamic conversations that feel natural and contextual

๐Ÿš€ Quick Start (For YouTube Viewers)

1. Install Python & Dependencies

# Install Python 3.8+ from python.org
# Then install dependencies
pip install -r requirements.txt

2. Setup Environment Variables

Create a .env file in the project folder:

# For Google Gemini (Free tier available)
GOOGLE_API_KEY=your_api_key_here

# For OpenAI (Paid)
OPENAI_API_KEY=your_api_key_here

# Optional: Enable features
ENABLE_SCREENSHOT=1
ENABLE_GOSSIP=1
GENERATION_SUPPRESS_SECONDS=25

3. Run Animal Crossing in Dolphin

  • Download Dolphin emulator
  • Load Animal Crossing (GAFE01) ROM
  • โš ๏ธ IMPORTANT: Start the game and wait until you're past the loading screen and in the actual game world
  • Get to a conversation with a villager

4. Launch the Mod

# Watch mode - continuously generates dialogue
python ac_parser_encoder.py --watch

# One-shot mode - generate once
python ac_parser_encoder.py --write

๐ŸŽฎ How It Works

  1. Memory Reading: Connects to Dolphin's memory to read current dialogue
  2. Context Analysis: Captures screenshots and analyzes conversation context
  3. AI Generation: Uses LLM to create natural, contextual responses
  4. Memory Writing: Encodes and writes new dialogue back to the game
  5. Real-time Updates: Continuously monitors and updates conversations

๐Ÿ”ง Advanced Usage

Watch Mode (Recommended for YouTube)

# Continuous monitoring with custom settings
python ac_parser_encoder.py --watch --interval 0.1 --size 512 --print-all

Custom Addresses

# Monitor multiple dialogue addresses
python ac_parser_encoder.py --watch --addresses 0x81298360 0x81298380

Debug Mode

# See raw hex data
python ac_parser_encoder.py --dump

๐ŸŒŸ Features

  • Smart Dialogue Generation: Context-aware responses based on game state
  • Real-time Updates: Continuous monitoring and generation
  • Screenshot Integration: Visual context for better AI responses
  • Gossip System: Villagers remember and reference past conversations
  • Multi-LLM Support: Google Gemini and OpenAI compatibility
  • Memory Safety: Prevents overwriting during active conversations

๐ŸŽฏ Perfect for YouTube Content

  • Interactive Streams: Let viewers suggest conversation topics
  • AI Villager Showcases: Demonstrate different personality types
  • Modding Tutorials: Show how to create custom game experiences
  • AI Gaming Content: Explore the future of AI-powered games

๐Ÿ› ๏ธ Technical Details

  • Memory Engine: Uses dolphin-memory-engine for GameCube memory access
  • Text Encoding: Full Animal Crossing character set and control code support
  • LLM Integration: Modular design supporting multiple AI providers
  • Cross-Platform: Works on Windows, macOS, and Linux

๐Ÿšจ Important Notes

  • Emulator Only: This mod works with Dolphin emulator, not original hardware
  • Memory Addresses: May need adjustment for different game versions
  • API Costs: OpenAI usage incurs charges, Google Gemini has free tier
  • Game Compatibility: Tested with Animal Crossing (GAFE01) version

โš ๏ธ Known Issues & Limitations

  • ๐Ÿชฒ Some Obvious Bugs: This is a work-in-progress mod with known issues
  • ๐Ÿ–ฅ๏ธ Platform Testing: Only tested on macOS - Windows/Linux may have compatibility issues
  • ๐ŸŽฎ Timing Critical: Must start the mod AFTER entering the game world (past loading screen)
  • ๐Ÿ’พ Memory Stability: May occasionally crash or behave unexpectedly
  • ๐Ÿ”ง Experimental: This is experimental software - use at your own risk!

๐Ÿ› Bug Reports & Contributions

PRs are welcome! This mod needs help from the community to improve:

  • Fix platform compatibility issues
  • Resolve known bugs and crashes
  • Improve memory reading stability
  • Add new features and LLM providers
  • Test on different game versions and platforms

Found a bug? Want to help? Open an issue or submit a pull request!

๐Ÿค Contributing

Found a bug? Want to add features? Contributions are very welcome! This mod needs community help to become stable.

Most Needed:

  • ๐Ÿ› Bug Fixes: Fix crashes, memory issues, and platform compatibility
  • ๐Ÿ–ฅ๏ธ Platform Support: Test and fix Windows/Linux compatibility issues
  • ๐ŸŽฎ Game Versions: Test with different Animal Crossing versions
  • ๐Ÿ“ฑ UI Improvements: Better error handling and user feedback
  • ๐Ÿงช Testing: Help test on different systems and configurations

How to Help:

  • Report issues with detailed error messages and system info
  • Test on different platforms (Windows, Linux, different macOS versions)
  • Submit pull requests with fixes and improvements
  • Help improve documentation and setup instructions

Ready to bring your Animal Crossing villagers to life with AI? ๐ŸŽฎโœจ

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for animal-crossing-llm-mod

Similar Open Source Tools

For similar tasks

For similar jobs