AI-powered NPC companions for Terraria via tModLoader

Spawn intelligent NPCs that understand natural language commands. Tell them to mine, build, fight, or follow you—powered by LLMs (Groq, OpenAI, Gemini).

Status: Early/experimental. Expect rough edges.

• Features
• Requirements
• Quick Start
• Commands
• Configuration
• Installation
• Project Structure
• Troubleshooting
• Contributing
• License

• Natural Language Commands — Talk to NPCs using plain English via /terra tell
• Action System — Mining, digging, building, combat, pathfinding, and follow behaviors
• Multi-Agent Coordination — Multiple NPCs can collaborate on building tasks
• Multiple LLM Providers — Choose between Groq, OpenAI, or Gemini
• In-Game UI — Chat panel for real-time interaction
• Persistent Memory — NPCs remember context and world knowledge

1. Install the mod in tModLoader
2. Configure your API key: Settings → Mod Configuration → TerraAIMod
3. In-game, open chat and run:

/terra spawn Bob
/terra tell Bob follow me
/terra tell Bob mine some copper

/terra tell Bob dig down 50 blocks
/terra tell Bob build a small house here
/terra tell Bob attack nearby slimes
/terra tell Bob follow me and stay close

Access via Settings → Mod Configuration → TerraAIMod

Note: Config is client-side (ConfigScope.ClientSide). API keys are stored per-player and never synced to servers.

1. Clone the repository:

   git clone https://github.com/Finesssee/Terra.git

2. Copy TerraAIMod/ to your ModSources folder:

   Documents/My Games/Terraria/tModLoader/ModSources/TerraAIMod/
   

3. In tModLoader: Workshop → Develop Mods → Build + Reload

Build with dotnet by setting tMLPath to your tModLoader install:

Windows (Steam):

set "tMLPath=C:\Program Files (x86)\Steam\steamapps\common\tModLoader"
dotnet build TerraAIMod/TerraAIMod.csproj

Linux/macOS:

export tMLPath="$HOME/.steam/steam/steamapps/common/tModLoader"
dotnet build TerraAIMod/TerraAIMod.csproj

Output .tmod file goes to:

Documents/My Games/Terraria/tModLoader/Mods/

TerraAIMod/
├── TerraAIMod.cs          # Main mod entry point
├── AI/                    # LLM clients and prompt building
│   ├── ILLMClient.cs      # Provider interface
│   ├── GroqClient.cs
│   ├── OpenAIClient.cs
│   ├── GeminiClient.cs
│   ├── PromptBuilder.cs
│   ├── ResponseParser.cs
│   └── TaskPlanner.cs
├── Action/                # Action execution system
│   ├── ActionExecutor.cs
│   ├── ActionResult.cs
│   ├── Task.cs
│   ├── CollaborativeBuildManager.cs
│   └── Actions/           # Individual action implementations
│       ├── BaseAction.cs
│       ├── MineTileAction.cs
│       ├── DigAction.cs
│       ├── BuildStructureAction.cs
│       ├── PlaceTileAction.cs
│       ├── CombatAction.cs
│       ├── FollowPlayerAction.cs
│       ├── IdleFollowAction.cs
│       └── PathfindAction.cs
├── Commands/              # Chat command handlers
│   └── TerraCommand.cs
├── Config/                # Mod configuration
│   └── TerraConfig.cs
├── Memory/                # Context and world state
│   ├── TerraMemory.cs
│   └── WorldKnowledge.cs
├── NPCs/                  # NPC entity definition
│   └── TerraNPC.cs
├── Pathfinding/           # Navigation system
│   ├── TerrariaPathfinder.cs
│   ├── PathExecutor.cs
│   └── PathNode.cs
├── Players/               # Per-player state
│   └── TerraModPlayer.cs
├── Systems/               # tModLoader system hooks
│   ├── TerraSystem.cs
│   └── TerraManager.cs
└── UI/                    # In-game interface
    ├── TerraUIState.cs
    ├── ChatPanel.cs
    └── InputField.cs

You're missing tMLPath. Set it to your tModLoader installation directory before building.

• Verify the key is correct and has available credits
• Check that AIProvider matches the key you're using
• Look at tModLoader logs for error details

• Ensure you spelled the NPC name correctly
• Check that the NPC is spawned with /terra list
• Verify your API key is configured

• NPCs cannot path through solid blocks without mining
• Complex terrain may cause navigation failures
• Try giving simpler, more direct commands

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m 'Add your feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

MIT

• Original concept: Steve AI by YuvDwi
• tModLoader team
• LLM providers: OpenAI, Groq, Google (Gemini)