valheim-ai-agent

An AI agent framework for controlling a Valheim character programmatically, using a BepInEx plugin as a game bridge and a Python agent powered by an LLM.

Inspired by Minecraft bot frameworks such as mineflayer, adapted to Valheim's closed binary via BepInEx modding.

Architecture

The system has three layers:

┌─────────────────────────────────────────────────────┐
│  Valheim Process                                    │
│  ┌───────────────────────────────────────────────┐  │
│  │  ValheimBotBridge (BepInEx C# plugin)         │  │
│  │  - Serializes game state to JSON              │  │
│  │  - Hosts WebSocket server on localhost:25500  │  │
│  │  - Executes action commands from agent        │  │
│  └───────────────────┬───────────────────────────┘  │
└──────────────────────│──────────────────────────────┘
                       │ WebSocket (ws://localhost:25500)
┌──────────────────────│──────────────────────────────┐
│  Python Agent        │                              │
│  ┌───────────────────▼───────────────────────────┐  │
│  │  valheim_agent.py                             │  │
│  │  - Receives game state                        │  │
│  │  - Calls LLM (Claude / GPT-4o)               │  │
│  │  - Sends action commands                      │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Data flow: Game state → WebSocket → Python agent → LLM → action command → WebSocket → game.

Repository Structure

valheim-ai-agent/
  README.md                  ← this file
  plugin/                    ← BepInEx C# plugin
    README.md                ← build & deployment guide
    ValheimBotBridge.csproj
    Plugin.cs
    WebSocketServer.cs
    StateSerializer.cs
    ActionHandler.cs
    Config.cs
    libs/                    ← local copies of reference DLLs (not committed)
  agent/                     ← Python AI agent
    README.md                ← setup & usage guide
    valheim_agent.py
    bridge.py
    state.py
    planner.py
    actions.py
    memory.py
    config.py
  docs/
    ARCHITECTURE.md          ← full technical architecture & implementation plan
  tests/
    test_bridge.py           ← Phase 1 tests (T01–T07)
    test_state.py            ← Phase 2 tests (T08–T16)
    test_llm.py              ← Phase 3 tests (T17–T22)

Prerequisites

System

Linux (tested on Pop!_OS 24.04)
.NET SDK 10 (dotnet --version to confirm)
Python 3.11+
Steam with Valheim installed

Valheim modding

r2modman installed
BepInEx installed via r2modman (denikson-BepInExPack_Valheim 5.4.2333)
An active r2modman profile for Valheim

API

An Anthropic or OpenAI API key (for the Python agent, Phase 3+)

Quick Start

These are the minimum steps to get from a fresh clone to a running plugin (Phase 1). See the per-module READMEs for full detail.

1. Populate the libs/ folder

Copy reference DLLs from your Valheim and BepInEx installations into plugin/libs/. Required files are listed in plugin/README.md.

2. Build the plugin

cd plugin
dotnet build -c Release

3. Deploy to r2modman

PROFILE="<your-profile-name>"
PLUGINS=~/.config/r2modmanPlus-local/Valheim/profiles/$PROFILE/BepInEx/plugins

cp plugin/bin/Release/netstandard2.1/ValheimBotBridge.dll $PLUGINS/
cp plugin/bin/Release/netstandard2.1/websocket-sharp.dll $PLUGINS/
cp plugin/bin/Release/netstandard2.1/Newtonsoft.Json.dll $PLUGINS/

4. Launch Valheim via r2modman (Start modded)

5. Verify the plugin loaded

tail -f ~/.config/r2modmanPlus-local/Valheim/profiles/$PROFILE/BepInEx/LogOutput.log

Expected output:

[Info   :   BepInEx] Loading [ValheimBotBridge 0.1.0]

6. Start the Python agent (Phase 3 — see agent/README.md)

cd agent
pip install -r requirements.txt
python valheim_agent.py

Release Flow

1. Build

cd plugin && dotnet build -c Release && cd ..

2. Stage DLLs into release/plugins/

bash scripts/prepare-release.sh

3. Update changelog, then commit

vim CHANGELOG.md git add release/plugins/ CHANGELOG.md git commit -m "Release v0.1.0"

4. Tag and push — this triggers the GitHub Action

git tag v0.1.0
git push origin main v0.1.0

Documentation Index

Document	Location	Description
This file	`README.md`	Project overview, architecture, quick start
Plugin guide	`plugin/README.md`	Building, deploying, and testing the BepInEx plugin
Agent guide	`agent/README.md`	Setting up and running the Python agent
Architecture & plan	`docs/ARCHITECTURE.md`	Full technical design, phase plan, and test suite (T01–T27)

Implementation Status

Phase	Description	Status
Phase 1	WebSocket bridge foundation	✅ Complete
Phase 2	Full state schema & all actions	✅ Complete
Phase 3	LLM integration	🔲 Not started
Phase 4	Hardening & stability	🔲 Not started

ValheimBotBridge