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...

CaptainHook - Valheim Discord Bridge Version: 4.0.0 by Caenos

🌩️ What is CaptainHook? CaptainHook is a lightweight, server-side mod that lets you connect your Valheim server to a Discord bot—delivering real-time info about players, server status, uptime, and more, all over a secure HTTP interface.

This update brings full per-command toggling via config, on-the-fly reloading, and smooth multi-server Discord integration. Built for ease of use and reliability—no log file scraping, no messy dependencies, and zero downtime for config changes!

✨ New in v4.0.0 🔄 Live Config Reload: Change your mod config and use the new /reload endpoint—no need to restart your server to update which commands are enabled.

⚙️ Per-Endpoint Toggles: Enable or disable any HTTP endpoint (/stats, /uptime, /version, /whereis, /commands, etc) directly from your config file.

🤖 Multi-Server Ready: Each server runs its own mod and exposes just the endpoints you want; your Discord bot can aggregate all servers and display results as one.

🗂️ Auto-generated Configs: The mod will auto-create Caenos.CaptainHook.cfg, seen.json, and debug.json if they're missing.

🧠 Cleaner API: Removed /day and dashboard endpoints for simplicity and accuracy.

🛡️ Designed for Dedicated Servers: No Valheim client required—just drop in on your server.

✅ Full Discord Slash Command Support (with included example bot).

📦 Installation

1. Server Setup Install BepInEx BepInExPack Valheim on Thunderstore

Drop CaptainHook.dll Place CaptainHook.dll into BepInEx/plugins/.

Start your server once. The config file BepInEx/config/Caenos.CaptainHook.cfg will be generated. Edit it to your needs:

ini Copy Edit [General] Port = 25681 BotName = CaptainHook ServerIP = 127.0.0.1

[Endpoints] EnableStats = true EnablePing = true EnableUptime = true EnableVersion = true EnableWhereIs = true EnableCommands = true ; EnableDay = false # /day endpoint is removed in 4.0.0

No server restart needed for config changes! Just hit the /reload endpoint with your bot or browser to re-read the config instantly.

1. Discord Bot Integration The mod is designed to work with the provided Python Discord bot template

Each server can run its own instance of CaptainHook, and the bot can fetch stats from all servers (S1, S2, S3, etc) and merge/forward results in Discord

See full example bot code below (supports /stats, /uptime, /whereis, /seen, /version, more...)

🚀 Features 📡 Discord bot support: Real-time stats and slash command integration

🧍 View online players and their biomes (/whereis)

⏱️ Get server uptime

🔗 All endpoints toggleable in config

🛠️ No restarts for config changes

📁 Auto-creates needed config and JSON files

⚡ No log scraping, file sharing, or modded clients needed

✅ Safe for dedicated servers

🤖 Example Discord Bot Commands /stats — Lists all online players from all your servers

/whereis <name> — Shows a player’s biome (per-server)

/uptime — Displays server uptime

/version — Shows mod version and author

/reload — Reloads the mod config on the fly

/seen <name> — When was a player last seen online (Discord-bot only)

/commands — Lists all commands and descriptions

🔒 Security Notes The HTTP server is read-only; it never accepts commands or controls the game/server

For extra safety, use a firewall or reverse proxy to restrict access to your bot’s IP

🙌 Credits Mod developed by Caenos Discord Bot example, testing, and feedback from the community

📂 Source / Repository Coming soon on GitHub...