CaptainHook - Valheim Discord Bridge

CaptainHook is a lightweight Valheim server mod that opens a simple HTTP interface so your Discord bot can request real-time server information like online players, uptime, biome locations, and more.

Built for ease of use, server admins can set it up in minutes and customize settings through a config file. It's ideal for anyone who wants a bot to talk to their server — no file sharing, no messy log parsing, no complicated dependencies.

🌩️ Features

• 📡 Discord bot support for real-time Valheim stats
• 🧍 View online players and their biomes
• 🕒 Get server uptime and current in-game time
• 🔁 Uses HTTP (no port forwarding required if hosted locally)
• 🛠️ Easily customizable via config file (IP, port, bot name)
• ✅ Fully works on dedicated servers

📦 Installation

🔧 Server Setup (Valheim Server)

1. Install BepInEx on your Valheim dedicated server

   • https://valheim.thunderstore.io/package/denikson/BepInExPack_Valheim/

2. Download CaptainHook.dll

   • Place it into: BepInEx/plugins/

3. Start your server once.

   • This will generate the config file:

     BepInEx/config/Caenos.CaptainHook.cfg
     

4. Open the config file and edit the values:

   [General]
   ServerPort = 25662
   ServerIP = 31.214.xxx.xxx   # Your public IP
   BotDisplayName = CaptainHook
   

5. Restart the server — you're ready to connect a bot!

🤖 Discord Bot Setup

You'll need a simple bot that can query your Valheim server using HTTP. Here's how:

1. Create a bot at: https://discord.com/developers/applications
2. Set the bot token as an environment variable: DISCORD_TOKEN
3. Use the Python bot template (see below)
4. Invite the bot to your server

📜 Example Bot Code (Python)

import discord
import os
import requests

HTTP_SERVER = "http://your.ip.here:25662"  # Match the config file
TOKEN = os.environ['DISCORD_TOKEN']

intents = discord.Intents.default()
intents.message_content = True
client = discord.Client(intents=intents)

def get(endpoint):
    try:
        response = requests.get(f"{HTTP_SERVER}/{endpoint}", timeout=3)
        return response.text
    except:
        return "⚠️ Could not reach server"

@client.event
async def on_ready():
    print(f"Logged in as {client.user}")

@client.event
async def on_message(message):
    if message.author.bot:
        return
    msg = message.content.lower()
    if msg == "@stats":
        await message.channel.send(get("stats"))
    elif msg.startswith("@w "):
        await message.channel.send(get(f"whereis?name={message.content[3:].strip()}"))
    elif msg == "@uptime":
        await message.channel.send(get("uptime"))
    elif msg == "@version":
        await message.channel.send(get("version"))
    elif msg == "@day":
        await message.channel.send(get("day"))
    elif msg == "@ping":
        await message.channel.send(get("ping"))
    elif msg == "@commands":
        await message.channel.send(
            """📜 Available Commands:
@stats - Online players
@w <name> - Player's biome
@ping - Server ping
@uptime - Server uptime
@version - Mod version
@day - In-game day/time
@commands - This list""")

client.run(TOKEN)

✅ Bot Commands

🔒 Security Notes

• This mod opens an HTTP port — it does not use encryption.
• It is read-only and does not allow any control commands.
• If you’re using a public server, consider a reverse proxy or local firewall to restrict access.

🧠 Tips

• You can host the bot anywhere — even on Replit, a Raspberry Pi, or a VPS
• If you're behind NAT or don't have port forwarding, consider using a tunnel like ngrok
• The mod works even if no players are online — great for uptime monitors!

🧪 Planned Features

• Discord slash command support
• Embedded visual status replies
• Admin ping alerts for server down

🙌 Credits

Mod developed by Caenos

📂 Source / Repository

Coming soon on GitHub...